/ Hex Artifact Content
Login

Artifact daa5e94df834537708afb917e9b4cc4489c63c00:


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 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6040: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6050: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6060: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6070: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6080: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6090: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60a0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
60b0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60c0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
60d0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
60e0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
60f0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6100: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6110: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6120: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6130: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6140: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6150: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6170: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6180: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6190: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
61a0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
61b0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
61c0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
61d0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
61e0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
61f0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6200: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6210: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6220: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6240: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6250: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6260: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6270: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6290: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
62a0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
62b0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
62c0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
62d0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
62e0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
62f0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
6320: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6340: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6350: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6360: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6370: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6390: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
63a0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
63b0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
63c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
63d0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
63e0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
63f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
6400: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
6410: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
6420: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
6430: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
6440: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
6450: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
6460: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
6470: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
6480: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
6490: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
64a0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
64b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
64c0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
64d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
64e0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
64f0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
6500: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
6510: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
6520: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
6530: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6540: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
6550: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
6560: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
6570: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
6580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
6590: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
65a0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
65b0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
65c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
65d0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
65e0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
65f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
6600: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
6610: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
6620: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  fs] xOpen method
6630: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
6640: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6650: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
6660: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
6670: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
6680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6690: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
66a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
66b0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
66c0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
66d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
66e0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
66f0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
6700: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
6710: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
6720: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
6730: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
6740: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
6750: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e  .** If the xOpen
6760: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
6770: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6780: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
6790: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
67a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
67b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
67c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
67d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
67e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
67f0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64  e xOpen reported
6800: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
6810: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
6820: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
6830: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6840: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72   xOpen.** is for
6860: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65   the xOpen to se
6870: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
6880: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
6890: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ent to NULL..**.
68a0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
68b0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
68c0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
68d0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
68e0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
68f0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
6900: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
6910: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
6920: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
6930: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
6940: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6950: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
6960: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6970: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
6980: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
6990: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
69a0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
69b0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
69c0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
69d0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
69e0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
69f0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
6a00: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6a10: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
6a20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6a30: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
6a40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6a50: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a70: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
6a80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
6aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6ab0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
6ac0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
6ad0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
6ae0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
6af0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
6b00: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
6b10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6b20: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
6b30: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
6b40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6b50: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
6b60: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
6b70: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
6b80: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
6b90: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
6ba0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
6bb0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
6bc0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
6bd0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
6be0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
6bf0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
6c00: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
6c10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
6c20: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6c30: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6c40: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6c50: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6c60: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6c70: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6c80: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6c90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6ca0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6cb0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6cc0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
6cd0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
6ce0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
6cf0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
6d00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
6d10: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
6d20: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
6d30: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
6d40: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
6d50: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
6d60: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
6d70: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6d80: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6d90: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6da0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
6db0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
6dc0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
6dd0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
6de0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
6df0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
6e00: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
6e10: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
6e20: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
6e30: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
6e40: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
6e50: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
6e60: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
6e70: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
6e80: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
6e90: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6ea0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6eb0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
6ec0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6ed0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
6ee0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
6ef0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
6f00: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
6f10: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6f20: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6f30: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6f40: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
6f50: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
6f60: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
6f70: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  cts..**.** The x
6f80: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
6f90: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
6fa0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
6fb0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
6fc0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
6fd0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
6fe0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
6ff0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7000: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7010: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7020: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7030: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7040: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7050: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7060: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7070: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7080: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7090: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
70a0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
70b0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
70c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7110: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7130: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7150: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7170: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7180: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7190: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
71a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
71b0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
71c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
71d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
71e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
71f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7200: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7210: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7220: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7230: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7240: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7250: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7260: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7270: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7280: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7290: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
72a0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
72b0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
72c0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
72d0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
72e0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
72f0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7300: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7310: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7320: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7330: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7340: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7350: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7360: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
7370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
7380: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
7390: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
73a0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
73c0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
73d0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
73e0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
73f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7400: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
7410: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
7420: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
7430: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
7440: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
7450: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
7460: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
7470: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
7480: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
7490: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
74a0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
74b0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
74c0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
74d0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
74e0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
74f0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
7500: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
7510: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
7520: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
7530: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
7540: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
7550: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
7560: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
7570: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
7580: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7590: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
75a0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
75b0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
75c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
75d0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
75e0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
75f0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
7600: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7610: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
7620: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
7630: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7640: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7650: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
7660: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
7670: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7690: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
76a0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
76b0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
76c0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
76d0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
76e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
76f0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
7700: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
7710: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7720: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
7730: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
7740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7750: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
7760: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
7770: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7780: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
7790: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
77a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
77b0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
77c0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
77d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
77e0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
77f0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
7800: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7810: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
7820: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7830: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
7840: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
7850: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7860: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
7870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
7880: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
7890: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
78a0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
78b0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
78c0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
78d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
78e0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
78f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
7900: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
7910: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
7920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
7930: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
7940: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
7950: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
7960: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7970: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
7980: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
7990: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
79a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
79b0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
79c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
79d0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
79e0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
79f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
7a00: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
7a10: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
7a20: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7a30: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
7a40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
7a60: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7a80: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
7a90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7aa0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7ab0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7ac0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
7ad0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
7ae0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
7af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7b00: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
7b10: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
7b20: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
7b30: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
7b40: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
7b50: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
7b60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7b70: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
7b80: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7b90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ba0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
7bb0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
7bc0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
7bd0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
7be0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
7bf0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
7c00: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
7c10: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
7c20: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
7c30: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
7c40: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
7c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
7c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
7c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
7ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
7cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
7cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
7cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
7ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
7cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
7d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
7d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
7d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
7d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
7d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
7d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
7d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
7d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
7d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
7d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
7da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
7db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
7dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
7de0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
7df0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
7e00: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
7e10: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
7e20: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
7e30: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
7e40: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
7e50: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
7e60: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
7e70: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
7e80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
7e90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7ea0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
7eb0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
7ec0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
7ed0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
7ee0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
7ef0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
7f00: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
7f10: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
7f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
7f30: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
7f40: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
7f50: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
7f60: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
7f70: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
7f80: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
7f90: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
7fa0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23  me systems..*/.#
7fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7fc0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
7fd0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
7fe0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
7ff0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
8000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
8010: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
8020: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
8030: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
8040: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
8050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8060: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
8070: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
8080: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8090: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23  K_SIZE       6.#
80a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
80b0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
80c0: 20 20 20 20 20 37 0a 0a 0a 2f 2a 0a 2a 2a 20 43       7.../*.** C
80d0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
80e0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
80f0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
8100: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
8110: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
8120: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
8130: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
8140: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
8150: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
8160: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
8170: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
8180: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
8190: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
81a0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
81b0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
81c0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
81d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
81e0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
81f0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
8200: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
8210: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
8220: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8230: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
8240: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
8250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
8260: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
8270: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
8280: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
8290: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
82a0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
82b0: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
82c0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
82d0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
82e0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
82f0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
8300: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
8310: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
8320: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
8330: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
8340: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
8350: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
8360: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
8370: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
8380: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
8390: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
83a0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
83b0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
83c0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
83d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
83e0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
83f0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
8400: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
8410: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
8420: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
8430: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
8440: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
8450: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
8460: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
8470: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
8480: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
8490: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
84a0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
84b0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
84c0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
84d0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
84e0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
84f0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
8500: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
8510: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
8520: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
8530: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
8540: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
8550: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
8560: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
8570: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
8580: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
8590: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
85a0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
85b0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
85c0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
85d0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
85e0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
85f0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
8600: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
8610: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
8620: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
8630: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
8640: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
8650: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
8660: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
8670: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
8680: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
8690: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
86a0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
86b0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
86c0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
86d0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
86e0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
86f0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
8700: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
8710: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
8720: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
8730: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
8740: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
8750: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
8760: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
8770: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
8780: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
8790: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
87a0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
87b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
87c0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
87d0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
87e0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
87f0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
8800: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
8810: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
8820: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
8830: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
8840: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
8850: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
8860: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
8870: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
8880: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8890: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
88a0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
88b0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
88c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
88d0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
88e0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
88f0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
8900: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
8910: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
8920: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8930: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
8940: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
8950: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
8960: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
8970: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
8980: 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  0 alphanumeric a
8990: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
89a0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
89b0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
89c0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
89d0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
89e0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
89f0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
8a00: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
8a10: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
8a20: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
8a30: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
8a40: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
8a50: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
8a60: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
8a70: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
8a80: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
8a90: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
8aa0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
8ab0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
8ac0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
8ad0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
8ae0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
8af0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
8b00: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
8b10: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
8b20: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
8b30: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
8b40: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
8b50: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
8b60: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
8b70: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
8b80: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
8b90: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
8ba0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8bb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
8bc0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
8bd0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
8be0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
8bf0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
8c00: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8c10: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
8c20: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
8c30: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
8c40: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
8c50: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
8c60: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
8c70: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
8c80: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
8c90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
8ca0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
8cb0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
8cc0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
8cd0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
8ce0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
8cf0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
8d00: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
8d10: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
8d20: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
8d30: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
8d40: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
8d50: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8d60: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8d70: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
8d80: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
8d90: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
8da0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
8db0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
8dc0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
8dd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8de0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
8df0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
8e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8e10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8e20: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
8e30: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8e40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
8e50: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
8e60: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8e70: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
8e80: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8e90: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
8ea0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
8eb0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
8ec0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
8ed0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
8ee0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
8ef0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
8f00: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
8f10: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
8f20: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
8f30: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
8f40: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
8f50: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
8f60: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
8f70: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
8f80: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
8f90: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
8fa0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
8fb0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
8fc0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
8fd0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
8fe0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
8ff0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
9000: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
9010: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
9020: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
9030: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
9040: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
9050: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
9060: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
9070: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
9080: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
9090: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
90a0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
90b0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
90c0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
90d0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
90e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
90f0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
9100: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
9110: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
9120: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
9130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
9140: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
9150: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
9160: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
9170: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
9180: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
9190: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
91a0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
91b0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
91c0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
91d0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
91e0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
91f0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9200: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
9210: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
9220: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
9230: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
9240: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
9250: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
9260: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
9270: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
9280: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
9290: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
92a0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
92b0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
92c0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
92d0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
92e0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
92f0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
9300: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
9310: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
9320: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
9330: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
9340: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
9350: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
9360: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
9370: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
9380: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
9390: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
93a0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
93b0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
93c0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
93d0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
93e0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
93f0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
9400: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
9410: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
9420: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
9430: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
9440: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
9450: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
9460: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
9470: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
9480: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
9490: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
94a0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
94b0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
94c0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
94d0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
94e0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
94f0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
9500: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
9510: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
9520: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
9530: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
9540: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
9550: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
9560: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9570: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
9580: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
9590: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
95a0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
95b0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
95c0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
95d0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
95e0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
95f0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
9600: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
9610: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
9620: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
9630: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
9640: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
9650: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
9660: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
9670: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
9680: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
9690: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
96a0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
96b0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
96c0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
96d0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
96e0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
96f0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
9700: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
9710: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
9720: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
9730: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
9740: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
9750: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
9760: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
9770: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
9780: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
9790: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
97a0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
97b0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
97c0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
97d0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
97e0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
97f0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
9800: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
9810: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
9820: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
9830: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
9840: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
9850: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
9860: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
9870: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
9880: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
9890: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
98a0: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
98b0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
98c0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
98d0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
98e0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
98f0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
9900: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
9910: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
9920: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
9930: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
9940: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
9950: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
9960: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
9970: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
9980: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
9990: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
99a0: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
99b0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
99c0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
99d0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
99e0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
99f0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
9a00: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
9a10: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
9a20: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
9a30: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
9a40: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
9a50: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
9a60: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
9a70: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
9a80: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
9a90: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
9aa0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
9ab0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
9ac0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
9ad0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
9ae0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
9af0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
9b00: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
9b10: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
9b20: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
9b30: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
9b40: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
9b50: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
9b60: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
9b70: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
9b80: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
9b90: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
9ba0: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
9bb0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9bc0: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
9bd0: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
9be0: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
9bf0: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
9c00: 74 69 70 6c 65 64 20 62 79 20 38 36 34 30 30 30  tipled by 864000
9c10: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
9c20: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
9c30: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
9c40: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
9c50: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
9c60: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
9c70: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
9c80: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
9c90: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
9ca0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
9cb0: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
9cc0: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
9cd0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
9ce0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
9cf0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
9d00: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
9d10: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
9d20: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
9d30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9d40: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
9d50: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
9d60: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
9d70: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75  qlite3_vfs;.stru
9d80: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
9d90: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
9da0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
9db0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
9dc0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
9dd0: 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 2) */.  int s
9de0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
9df0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
9e00: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
9e10: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
9e20: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
9e30: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
9e40: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
9e50: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
9e60: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
9e70: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
9e80: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
9e90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9ea0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
9eb0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
9ec0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
9ed0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
9ee0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
9ef0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
9f00: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
9f10: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
9f20: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9f30: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9f40: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
9f50: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
9f60: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
9f70: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
9f80: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
9f90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9fa0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9fb0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
9fc0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
9fd0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9fe0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9ff0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
a000: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
a010: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
a020: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a030: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
a040: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
a050: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
a060: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
a070: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a080: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
a090: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
a0a0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
a0b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
a0c0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
a0d0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
a0e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
a0f0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
a100: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
a110: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
a120: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
a130: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
a140: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
a150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
a160: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
a170: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
a180: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
a190: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
a1a0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
a1b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
a1c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
a1d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
a1e0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
a1f0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
a200: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
a210: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
a220: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
a230: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
a240: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
a250: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
a260: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
a270: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
a280: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
a290: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
a2a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
a2b0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
a2c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
a2d0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
a2e0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
a2f0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
a300: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
a310: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
a320: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
a330: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
a340: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
a350: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
a360: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
a370: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
a380: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
a390: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
a3a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
a3b0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
a3c0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
a3d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
a3e0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
a3f0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
a400: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
a410: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
a420: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
a430: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
a440: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
a450: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
a460: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
a470: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
a480: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
a490: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
a4a0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
a4b0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
a4c0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
a4d0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
a4e0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
a4f0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
a500: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
a510: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
a520: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
a530: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
a540: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
a550: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
a560: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
a570: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
a580: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
a590: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
a5a0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
a5b0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
a5c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
a5d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
a5e0: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
a5f0: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
a600: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
a610: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
a620: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
a630: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
a640: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
a650: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
a660: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
a670: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
a680: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
a690: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
a6a0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
a6b0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
a6c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
a6d0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
a6e0: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
a6f0: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
a700: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
a710: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
a720: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
a730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
a740: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
a750: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
a760: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a770: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
a780: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
a790: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
a7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
a7b0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
a7c0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
a7d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a7e0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
a7f0: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
a800: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
a810: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
a820: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
a830: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
a840: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
a850: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
a860: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
a870: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a880: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
a890: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
a8a0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
a8b0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
a8c0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
a8d0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
a8e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
a8f0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
a900: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
a910: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a920: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
a930: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
a940: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a950: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
a960: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
a970: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
a980: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
a990: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
a9a0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
a9b0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
a9c0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
a9d0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
a9e0: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
a9f0: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
aa00: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
aa10: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
aa20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
aa30: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
aa40: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
aa50: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
aa60: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
aa70: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
aa80: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
aa90: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
aaa0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
aab0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
aac0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
aad0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
aae0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
aaf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ab00: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
ab10: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
ab20: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
ab30: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
ab40: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
ab50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ab60: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
ab70: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
ab80: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ab90: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
aba0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
abb0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
abc0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
abd0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
abe0: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
abf0: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
ac00: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
ac10: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
ac20: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
ac30: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
ac40: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
ac50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ac60: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
ac70: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
ac80: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
ac90: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
aca0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
acb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
acc0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
acd0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
ace0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
acf0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
ad00: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
ad10: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
ad20: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
ad30: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
ad40: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
ad50: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
ad60: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ad70: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
ad80: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
ad90: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
ada0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
adb0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
adc0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
add0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
ade0: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
adf0: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
ae00: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
ae10: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
ae20: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
ae30: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
ae40: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
ae50: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ae60: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
ae70: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
ae80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ae90: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
aea0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
aeb0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
aec0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
aed0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
aee0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
aef0: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
af00: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
af10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
af20: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
af30: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
af40: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
af50: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
af60: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
af70: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
af80: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
af90: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
afa0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
afb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
afc0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
afd0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
afe0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
aff0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
b000: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
b010: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
b020: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
b030: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
b040: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
b050: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b060: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
b070: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
b080: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
b090: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
b0a0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
b0b0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
b0c0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
b0d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b0e0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
b0f0: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
b100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b110: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
b120: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
b130: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
b140: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
b150: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
b160: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
b170: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
b180: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
b190: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
b1a0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
b1b0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
b1c0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
b1d0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
b1e0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
b1f0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
b200: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
b210: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
b220: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
b230: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
b240: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
b250: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
b260: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
b270: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
b280: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
b290: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
b2a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
b2b0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
b2c0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
b2d0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
b2e0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
b2f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b300: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
b310: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
b320: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
b330: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
b340: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
b350: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
b360: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
b370: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
b380: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
b390: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
b3a0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
b3b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b3c0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
b3d0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
b3e0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
b3f0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
b400: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
b410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
b420: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
b430: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
b440: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b450: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
b460: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
b470: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
b480: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
b490: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
b4a0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
b4b0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
b4c0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
b4d0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
b4e0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
b4f0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
b500: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
b510: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
b520: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
b530: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
b540: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
b550: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
b560: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
b570: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
b580: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
b590: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
b5a0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
b5b0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
b5c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
b5d0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
b5e0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
b5f0: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
b600: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
b610: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b620: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
b630: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
b640: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
b650: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
b660: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
b670: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b680: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
b690: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
b6a0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
b6b0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
b6c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
b6d0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
b6e0: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
b6f0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
b700: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
b710: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
b720: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
b730: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
b740: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
b750: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
b760: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
b770: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
b780: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
b790: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
b7a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
b7b0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
b7c0: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
b7d0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
b7e0: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
b7f0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
b800: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
b810: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
b820: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
b830: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
b840: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
b850: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
b860: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
b870: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
b880: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
b890: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
b8a0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
b8b0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b8c0: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
b8d0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
b8e0: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
b8f0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
b900: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
b910: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
b920: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
b930: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
b940: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
b950: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
b960: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
b970: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
b980: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
b990: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
b9a0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
b9b0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
b9c0: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
b9d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b9e0: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
b9f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
ba00: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
ba10: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
ba20: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
ba30: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
ba40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ba50: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
ba60: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
ba70: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
ba80: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
ba90: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
baa0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
bab0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
bac0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
bad0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
bae0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
baf0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
bb00: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
bb10: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
bb20: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
bb30: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
bb40: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
bb50: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
bb60: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
bb70: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
bb80: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
bb90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
bba0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
bbb0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
bbc0: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
bbd0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
bbe0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
bbf0: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
bc00: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
bc10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
bc20: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bc30: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
bc40: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
bc50: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
bc60: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
bc70: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
bc80: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
bc90: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
bca0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bcb0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
bcc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
bcd0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
bce0: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
bcf0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
bd00: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
bd10: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
bd20: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
bd30: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
bd40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
bd50: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
bd60: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
bd70: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
bd80: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
bd90: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
bda0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
bdb0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
bdc0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
bdd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
bde0: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
bdf0: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
be00: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
be10: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
be20: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
be30: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
be40: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
be50: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
be60: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
be70: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
be80: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
be90: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
bea0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
beb0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
bec0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
bed0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
bee0: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
bef0: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
bf00: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
bf10: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
bf20: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
bf30: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bf40: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
bf50: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
bf60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
bf70: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
bf80: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
bf90: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
bfa0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
bfb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bfc0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
bfd0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
bfe0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
bff0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
c000: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
c010: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
c020: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
c030: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
c040: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c050: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
c060: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
c070: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
c080: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
c090: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
c0a0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
c0b0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
c0c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
c0d0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
c0e0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
c0f0: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
c100: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
c110: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c120: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
c130: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
c140: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c150: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
c160: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
c170: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
c180: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
c190: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
c1a0: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
c1b0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
c1c0: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
c1d0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
c1e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
c1f0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
c200: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
c210: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
c220: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
c230: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
c240: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
c250: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
c260: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
c270: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
c280: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
c290: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
c2a0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
c2b0: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
c2c0: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
c2d0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
c2e0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
c2f0: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
c300: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
c310: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
c320: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
c330: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c340: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
c350: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c360: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
c370: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
c380: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
c390: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
c3a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c3b0: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
c3c0: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
c3d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c3e0: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
c3f0: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
c400: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
c410: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
c420: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
c430: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
c440: 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65   argument).  The
c450: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  .** sqlite3_db_c
c460: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c470: 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65  e should only be
c480: 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c   used immediatel
c490: 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64  y after.** the d
c4a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c4b0: 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73  on is created us
c4c0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
c4d0: 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  n()],.** [sqlite
c4e0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
c4f0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
c500: 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
c510: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
c520: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
c530: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
c540: 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67  is the.** config
c550: 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61  uration verb - a
c560: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
c570: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
c580: 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20  at.** aspect of 
c590: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
c5a0: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
c5b0: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
c5c0: 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63  * The only choic
c5d0: 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65  e for this value
c5e0: 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f   is [SQLITE_DBCO
c5f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e  NFIG_LOOKASIDE].
c600: 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72  .** New verbs ar
c610: 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61  e likely to be a
c620: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
c630: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
c640: 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  e..** Additional
c650: 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e   arguments depen
c660: 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a  d on the verb..*
c670: 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
c680: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c690: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
c6a0: 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
c6b0: 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
c6c0: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
c6d0: 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
c6e0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c6f0: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
c700: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
c710: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
c720: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
c730: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
c740: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
c750: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
c760: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
c770: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
c780: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
c790: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c7a0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
c7b0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
c7c0: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
c7d0: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
c7e0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
c7f0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
c800: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
c810: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
c820: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
c830: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
c840: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
c850: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
c860: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
c870: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
c880: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
c890: 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
c8a0: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
c8b0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
c8c0: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
c8d0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
c8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
c8f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
c900: 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
c910: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
c920: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
c930: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
c940: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
c950: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
c960: 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
c970: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
c980: 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
c990: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
c9a0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
c9b0: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
c9c0: 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
c9d0: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
c9e0: 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
c9f0: 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
ca00: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
ca10: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
ca20: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
ca30: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
ca40: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
ca50: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
ca60: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
ca70: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
ca80: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
ca90: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
caa0: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
cab0: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
cac0: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
cad0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
cae0: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
caf0: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
cb00: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
cb10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
cb20: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
cb30: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
cb40: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
cb50: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
cb60: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
cb70: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
cb80: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
cb90: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
cba0: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20  .** The xMalloc 
cbb0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
cbc0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
cbd0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cbe0: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
cbf0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
cc00: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
cc10: 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c  y..** The xReall
cc20: 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77  oc method must w
cc30: 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63  ork like realloc
cc40: 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  () from the stan
cc50: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a  dard C library.*
cc60: 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70  * with the excep
cc70: 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65  tion that if the
cc80: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
cc90: 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20   to xRealloc is 
cca0: 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  zero,.** xReallo
ccb0: 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f  c must be a no-o
ccc0: 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20  p - it must not 
ccd0: 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f  perform any allo
cce0: 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61  cation or.** dea
ccf0: 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c  llocation.  ^SQL
cd00: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
cd10: 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
cd20: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
cd30: 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
cd40: 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
cd50: 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
cd60: 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
cd70: 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65  * And so in case
cd80: 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70  s where xRoundup
cd90: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
cda0: 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
cdb0: 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63  r,.** xRealloc c
cdc0: 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74  an perform exact
cdd0: 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61  ly as the standa
cde0: 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c  rd library reall
cdf0: 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c  oc() and.** stil
ce00: 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e  l be in complian
ce10: 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65  ce with this spe
ce20: 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  cification..**.*
ce30: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
ce40: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
ce50: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
ce60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
ce70: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
ce80: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
ce90: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
cea0: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
ceb0: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
cec0: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
ced0: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
cee0: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
cef0: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
cf00: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
cf10: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
cf20: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
cf30: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
cf40: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
cf50: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
cf60: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
cf70: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
cf80: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
cf90: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
cfa0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cfb0: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
cfc0: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
cfd0: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
cfe0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
cff0: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
d000: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
d010: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
d020: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
d030: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
d040: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
d050: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
d060: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
d070: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
d080: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
d090: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
d0a0: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
d0b0: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
d0c0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
d0d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d0e0: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
d0f0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
d100: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
d110: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
d120: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
d130: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
d140: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
d150: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
d160: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
d170: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
d180: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
d190: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
d1a0: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
d1b0: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
d1c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
d1d0: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
d1e0: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
d1f0: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
d200: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
d210: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
d220: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
d230: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
d240: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
d250: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
d260: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
d270: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
d280: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
d290: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
d2a0: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
d2b0: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
d2c0: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
d2d0: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
d2e0: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
d2f0: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
d300: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
d310: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d320: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
d330: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
d340: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
d350: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
d360: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
d370: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
d380: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
d390: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
d3a0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
d3b0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
d3c0: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
d3d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d3e0: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
d3f0: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
d400: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
d410: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
d420: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
d430: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
d440: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
d450: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
d460: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
d470: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
d480: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
d490: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
d4a0: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
d4b0: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
d4c0: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
d4d0: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
d4e0: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
d4f0: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
d500: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
d510: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
d520: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
d530: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
d540: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d550: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d560: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
d570: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
d580: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d590: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
d5a0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
d5b0: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
d5c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
d5d0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
d5e0: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
d5f0: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
d600: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
d610: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
d620: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
d630: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
d640: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
d650: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
d660: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
d670: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
d680: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
d690: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
d6a0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
d6b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
d6c0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
d6d0: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
d6e0: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
d6f0: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
d700: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
d710: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
d720: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
d730: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
d740: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
d750: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
d760: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
d770: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
d780: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
d790: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
d7a0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
d7b0: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
d7c0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
d7d0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
d7e0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
d7f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d800: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d810: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d820: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d830: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d840: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d850: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d860: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d870: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d880: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d890: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d8a0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d8b0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d8c0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d8d0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d8e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d8f0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d900: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d910: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d920: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d930: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d940: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d950: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d960: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d970: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d980: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d990: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d9a0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d9b0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d9c0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d9d0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d9e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d9f0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
da00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
da10: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
da20: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
da30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
da40: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
da50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
da60: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
da70: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
da80: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
da90: 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
daa0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
dab0: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
dac0: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
dad0: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
dae0: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
daf0: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
db00: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
db10: 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
db20: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
db30: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
db40: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
db50: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
db60: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
db70: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
db80: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
db90: 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
dba0: 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
dbb0: 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
dbc0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
dbd0: 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
dbe0: 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
dbf0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
dc00: 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
dc10: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
dc20: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
dc30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
dc40: 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
dc50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dc60: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
dc70: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dc80: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
dc90: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
dca0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
dcb0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
dcc0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
dcd0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
dce0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
dcf0: 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
dd00: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
dd10: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
dd20: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
dd30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
dd40: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
dd50: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
dd60: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
dd70: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
dd80: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
dd90: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
dda0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ddb0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
ddc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
ddd0: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
dde0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
ddf0: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
de00: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
de10: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
de20: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
de30: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
de40: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
de50: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
de60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
de70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
de80: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
de90: 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
dea0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
deb0: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
dec0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
ded0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
dee0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
def0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
df00: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
df10: 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
df20: 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
df30: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
df40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
df50: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
df60: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
df70: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
df80: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
df90: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
dfa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dfb0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
dfc0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
dfd0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
dfe0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
dff0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
e000: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
e010: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
e020: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
e030: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
e040: 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
e050: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
e060: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
e070: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
e080: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
e090: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
e0a0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
e0b0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
e0c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e0d0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
e0e0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
e0f0: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
e100: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
e110: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e120: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
e130: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
e140: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
e150: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
e160: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
e170: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e180: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
e190: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
e1a0: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
e1b0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
e1c0: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
e1d0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
e1e0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
e1f0: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
e200: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
e210: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
e220: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
e230: 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
e240: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e250: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
e260: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
e270: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e280: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
e290: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
e2a0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
e2b0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
e2c0: 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
e2d0: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
e2e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e2f0: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
e300: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
e310: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
e320: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
e330: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
e340: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e350: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
e360: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e370: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
e380: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e390: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e3a0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e3b0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e3c0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e3d0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e3e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e3f0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
e400: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
e410: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
e420: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
e430: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
e440: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
e450: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
e460: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
e470: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
e480: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
e490: 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
e4a0: 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
e4b0: 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
e4c0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
e4d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
e4e0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
e4f0: 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
e500: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
e510: 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
e520: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e530: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
e540: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
e550: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
e560: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
e570: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
e580: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
e590: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
e5a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
e5b0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
e5c0: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
e5d0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
e5e0: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
e5f0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
e600: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
e610: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e620: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
e630: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
e640: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
e650: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
e660: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
e670: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
e680: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
e690: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
e6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e6b0: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
e6c0: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
e6d0: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
e6e0: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
e6f0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e700: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
e710: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
e720: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
e730: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
e740: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
e750: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
e760: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
e770: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
e780: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
e790: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e7a0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
e7b0: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
e7c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
e7d0: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
e7e0: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
e7f0: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
e800: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
e810: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
e820: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
e830: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
e840: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
e850: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
e860: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
e870: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
e880: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
e890: 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
e8a0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
e8b0: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
e8c0: 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
e8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
e8e0: 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
e8f0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
e900: 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
e910: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
e920: 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
e930: 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
e940: 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
e950: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
e960: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
e970: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
e980: 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
e990: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e9a0: 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
e9b0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e9c0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e9d0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e9e0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e9f0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
ea00: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
ea10: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
ea20: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
ea30: 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
ea40: 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
ea50: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
ea60: 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
ea70: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
ea80: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
ea90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
eaa0: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
eab0: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
eac0: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
ead0: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
eae0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
eaf0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
eb00: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
eb10: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
eb20: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
eb30: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
eb40: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
eb50: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
eb60: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
eb70: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
eb80: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
eb90: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
eba0: 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
ebb0: 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
ebc0: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
ebd0: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
ebe0: 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
ebf0: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
ec00: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
ec10: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
ec20: 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
ec30: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
ec40: 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
ec50: 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
ec60: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
ec70: 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
ec80: 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
ec90: 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
eca0: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
ecb0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ecc0: 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
ecd0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
ece0: 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
ecf0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
ed00: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
ed10: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
ed20: 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
ed30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ed40: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
ed50: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
ed60: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
ed70: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
ed80: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
ed90: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
eda0: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
edb0: 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
edc0: 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
edd0: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74  cache implemenat
ede0: 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
edf0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
ee00: 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
ee10: 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
ee20: 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
ee30: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
ee40: 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
ee50: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
ee60: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f  _CONFIG_PCACHE o
ee70: 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
ee80: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
ee90: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
eea0: 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
eeb0: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
eec0: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
eed0: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
eee0: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
eef0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
ef00: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
ef10: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
ef20: 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
ef30: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
ef40: 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
ef50: 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
ef60: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
ef70: 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
ef80: 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
ef90: 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
efa0: 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
efb0: 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
efc0: 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
efd0: 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
efe0: 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
eff0: 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
f000: 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
f010: 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
f020: 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
f030: 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
f040: 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
f050: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
f060: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
f070: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
f080: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
f090: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
f0a0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
f0b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
f0c0: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
f0d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
f0e0: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
f0f0: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
f100: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
f110: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
f120: 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
f130: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
f140: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
f150: 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
f160: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
f170: 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
f180: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
f190: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
f1a0: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
f1b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
f1c0: 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
f1d0: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
f1e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f1f0: 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
f200: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
f210: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
f220: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
f230: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
f240: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
f250: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
f260: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
f270: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
f280: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
f290: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
f2a0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
f2b0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
f2c0: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
f2d0: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
f2e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
f2f0: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
f300: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
f310: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
f320: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
f330: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
f340: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
f350: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
f360: 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
f370: 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
f380: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
f390: 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
f3a0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
f3b0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
f3c0: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
f3d0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
f3e0: 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
f3f0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
f400: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
f410: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
f420: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
f430: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
f440: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
f450: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
f460: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
f470: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
f480: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
f490: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
f4a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f4b0: 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
f4c0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
f4d0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
f4e0: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
f4f0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
f500: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
f510: 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
f520: 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
f530: 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
f540: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
f550: 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
f560: 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
f570: 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
f580: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
f590: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
f5a0: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
f5b0: 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
f5c0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
f5d0: 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
f5e0: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
f5f0: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
f600: 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
f610: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
f620: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f630: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
f640: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
f650: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
f660: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
f670: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
f680: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
f690: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
f6a0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
f6b0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
f6c0: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
f6d0: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
f6e0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
f6f0: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
f700: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
f710: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
f720: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
f730: 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
f740: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
f750: 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
f760: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
f770: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f780: 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
f790: 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
f7a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f7b0: 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
f7c0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f7d0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
f7e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
f7f0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
f800: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
f810: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
f820: 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
f830: 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
f840: 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
f850: 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
f860: 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
f870: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
f880: 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
f890: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
f8a0: 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
f8b0: 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
f8c0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
f8d0: 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
f8e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f8f0: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
f900: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f910: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f920: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
f930: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
f940: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
f950: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
f960: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f970: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
f980: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
f990: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
f9a0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
f9b0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
f9c0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
f9d0: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
f9e0: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
f9f0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
fa00: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
fa10: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
fa20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
fa30: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
fa40: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
fa50: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
fa60: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
fa70: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
fa80: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
fa90: 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
faa0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fab0: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
fac0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
fad0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
fae0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
faf0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
fb00: 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
fb10: 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
fb20: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
fb30: 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
fb40: 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
fb50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
fb60: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
fb70: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
fb80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fb90: 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
fba0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
fbb0: 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
fbc0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fbd0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
fbe0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
fbf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
fc00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
fc10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
fc20: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
fc30: 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68  llocation for th
fc40: 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
fc50: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20  ry allocator on 
fc60: 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
fc70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
fc80: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
fc90: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
fca0: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
fcb0: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
fcc0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
fcd0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
fce0: 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
fcf0: 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
fd00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
fd10: 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  ^  ^(This option
fd20: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e   sets the.** <i>
fd30: 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
fd40: 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
fd50: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
fd60: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76  _LOOKASIDE].** v
fd70: 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  erb to [sqlite3_
fd80: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
fd90: 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
fda0: 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
fdb0: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
fdc0: 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
fdd0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
fde0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
fdf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
fe00: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
fe10: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
fe20: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
fe30: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
fe40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
fe50: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
fe60: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
fe70: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
fe80: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
fe90: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
fea0: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
feb0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
fec0: 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
fed0: 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
fee0: 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
fef0: 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
ff00: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
ff10: 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
ff20: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ff30: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
ff40: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
ff50: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
ff60: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
ff70: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
ff80: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
ff90: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
ffa0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
ffb0: 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
ffc0: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
ffd0: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
ffe0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
fff0: 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
10000 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
10010 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
10020 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
10030 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
10040 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
10050 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
10060 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
10070 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
10080 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
10090 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
100a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
100b0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
100c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
100d0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
100e0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
100f0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
10100 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
10110 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
10120 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
10130 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
10140 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
10150 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
10160 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
10170 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
10180 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
10190 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
101a0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
101b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
101c0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
101d0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
101e0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
101f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10200 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
10210 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
10220 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
10230 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
10240 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
10250 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
10260 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
10270 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10280 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
10290 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
102a0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
102b0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
102c0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
102d0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
102e0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
102f0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
10300 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10310 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
10320 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
10330 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
10340 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
10350 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
10360 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
10370 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
10380 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
10390 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
103a0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
103b0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
103c0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
103d0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
103e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
103f0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
10400 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
10410 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10420 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
10430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
10440 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
10450 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
10460 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
10470 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
10480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10490 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
104a0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
104b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
104c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
104d0 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
104e0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
104f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10500 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
10510 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10530 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
10540 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10550 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
10570 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
10580 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
10590 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
105a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
105b0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
105c0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
105d0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
105e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
105f0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
10600 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
10610 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
10620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10630 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
10640 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
10650 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
10660 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
10670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10680 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
10690 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
106a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
106b0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
106c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
106d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
106e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
106f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
10700 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
10710 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
10720 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
10730 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
10740 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
10750 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
10760 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
10770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
10780 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
10790 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
107a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
107b0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
107c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
107d0 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
107e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
107f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
10800 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65     15  /* sqlite
10810 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
10820 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
10830 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
10840 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
10850 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a  Func, void* */..
10860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10870 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
10880 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
10890 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
108a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
108b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
108c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
108d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
108e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
108f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
10900 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
10910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
10920 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10930 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
10940 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10950 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
10960 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
10970 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
10980 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
10990 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
109a0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
109b0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
109c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
109d0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
109e0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
109f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10a00 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
10a10 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
10a20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
10a30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10a40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
10a50 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
10a60 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10a70 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
10a80 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
10a90 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
10aa0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
10ab0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
10ac0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
10ad0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
10ae0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
10af0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10b00 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
10b10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
10b20 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
10b30 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
10b40 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
10b50 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
10b60 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
10b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10b80 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
10b90 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
10ba0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
10bb0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10bc0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
10bd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d  ointer to an mem
10be0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
10bf0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
10c00 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
10c10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
10c20 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
10c30 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10c40 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
10c50 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
10c60 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
10c70 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
10c80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
10c90 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
10ca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10cb0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
10cc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
10cd0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
10ce0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
10cf0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
10d00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
10d10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
10d20 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
10d30 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
10d40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10d50 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
10d60 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
10d70 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
10d80 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
10d90 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
10da0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
10db0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
10dc0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
10dd0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
10de0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
10df0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
10e00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
10e10 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
10e20 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
10e30 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
10e40 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
10e50 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
10e60 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
10e70 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
10e80 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
10e90 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
10ea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10eb0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
10ec0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
10ed0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
10ee0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
10ef0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
10f00 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
10f10 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
10f20 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
10f30 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
10f40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
10f50 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
10f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
10f70 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
10f80 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
10f90 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
10fa0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
10fb0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
10fc0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
10fd0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
10fe0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
10ff0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
11000 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
11010 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
11020 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
11030 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
11040 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
11050 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
11060 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
11070 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
11080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
11090 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
110a0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
110b0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
110c0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
110d0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
110e0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
110f0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
11100 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
11110 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
11120 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
11130 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
11140 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
11150 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
11160 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
11170 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
11180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11190 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
111a0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
111b0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
111c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
111d0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
111e0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
111f0 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
11200 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
11210 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
11220 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
11230 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
11240 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
11250 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
11260 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
11270 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
11280 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
11290 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
112a0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
112b0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
112c0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
112d0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
112e0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
112f0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
11300 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
11310 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
11320 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
11330 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
11340 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
11350 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
11360 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
11370 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
11380 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
11390 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
113a0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
113b0 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
113c0 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
113d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
113e0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
113f0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  st argument.  ^I
11400 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
11410 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
11420 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
11430 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
11440 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
11450 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
11460 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
11470 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
11480 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
11490 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
114a0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
114b0 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
114c0 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
114d0 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
114e0 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
114f0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
11500 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
11510 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
11520 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
11530 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
11540 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
11550 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
11560 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
11570 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a  igger fired.)^.*
11580 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
11590 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
115a0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
115b0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
115c0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
115d0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
115e0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
115f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
11600 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
11610 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
11620 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
11630 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
11640 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
11650 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
11660 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
11670 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
11680 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
11690 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
116a0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
116b0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
116c0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
116d0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
116e0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
116f0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
11700 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
11710 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
11720 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
11730 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
11740 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
11750 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
11760 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
11770 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
11780 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
11790 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
117a0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
117b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
117c0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
117d0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
117e0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
117f0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
11800 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
11810 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
11820 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
11830 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
11840 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
11850 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
11860 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
11870 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
11880 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
11890 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
118a0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
118b0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
118c0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
118d0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
118e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
118f0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
11900 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
11910 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
11920 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
11930 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
11940 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
11950 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
11960 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
11970 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
11980 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11990 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
119a0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
119b0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
119c0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
119d0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
119e0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
119f0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
11a00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
11a10 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
11a20 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
11a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11a40 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
11a50 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
11a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
11a70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
11a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
11a90 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
11aa0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
11ab0 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
11ac0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
11ad0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
11ae0 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
11af0 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
11b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11b10 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
11b20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11b30 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
11b40 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
11b50 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
11b60 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
11b70 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
11b80 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
11b90 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
11ba0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
11bb0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
11bc0 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
11bd0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
11be0 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
11bf0 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
11c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
11c10 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
11c20 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
11c30 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
11c40 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
11c50 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
11c60 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
11c70 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
11c80 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
11c90 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
11ca0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
11cb0 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
11cc0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
11cd0 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
11ce0 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
11cf0 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
11d00 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
11d10 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
11d20 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
11d30 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
11d40 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
11d50 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
11d60 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
11d70 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
11d80 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
11d90 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
11da0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
11db0 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
11dc0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
11dd0 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
11de0 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
11df0 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
11e00 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
11e10 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
11e20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
11e30 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11e40 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
11e50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
11e60 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
11e70 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
11e80 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
11e90 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
11ea0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
11eb0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
11ec0 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
11ed0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
11ee0 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
11ef0 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
11f00 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
11f10 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
11f20 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
11f30 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
11f40 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
11f50 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
11f60 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
11f70 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
11f80 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
11f90 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
11fa0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
11fb0 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
11fc0 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
11fd0 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
11fe0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
11ff0 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
12000 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
12010 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
12020 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
12030 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
12040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
12050 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
12060 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
12070 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
12080 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
12090 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
120a0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
120b0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
120c0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
120d0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
120e0 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
120f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
12100 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
12110 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
12120 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
12130 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
12140 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
12150 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
12160 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
12170 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
12180 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
12190 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
121a0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
121b0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
121c0 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
121d0 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
121e0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
121f0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
12200 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
12210 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
12220 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
12230 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
12240 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
12250 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
12260 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
12270 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
12280 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
12290 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
122a0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
122b0 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
122c0 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
122d0 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
122e0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
122f0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
12300 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
12310 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
12320 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
12330 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
12340 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
12350 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12360 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12370 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
12380 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
12390 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
123a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
123b0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
123c0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
123d0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
123e0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
123f0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
12400 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
12410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
12420 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
12430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12440 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
12450 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
12460 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12470 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12480 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
12490 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
124a0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
124b0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
124c0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
124d0 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
124e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
124f0 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
12500 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
12510 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
12520 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
12530 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
12540 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
12550 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
12560 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
12570 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
12580 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
12590 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
125a0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
125b0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
125c0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
125d0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
125e0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
125f0 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
12600 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
12610 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
12620 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
12630 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
12640 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
12650 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
12660 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
12670 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
12680 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
12690 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
126a0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
126b0 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
126c0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
126d0 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
126e0 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
126f0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
12700 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
12710 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
12720 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
12730 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
12740 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
12750 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
12760 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
12770 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
12780 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
12790 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
127a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
127b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
127c0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
127d0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
127e0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
127f0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
12800 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
12810 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
12820 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
12830 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
12840 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
12850 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
12860 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12870 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
12880 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
12890 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
128a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
128b0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
128c0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
128d0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
128e0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
128f0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
12900 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
12920 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
12930 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
12940 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
12950 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
12960 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
12970 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
12980 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
12990 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
129a0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
129b0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
129c0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
129d0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
129e0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
129f0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
12a00 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
12a10 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
12a20 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
12a30 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
12a40 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
12a50 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
12a60 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
12a70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
12a80 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
12a90 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
12aa0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
12ab0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
12ac0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
12ad0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
12ae0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
12af0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
12b00 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
12b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b20 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
12b30 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
12b40 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
12b50 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12b60 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
12b70 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
12b80 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
12b90 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
12ba0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
12bb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12bc0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
12bd0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
12be0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
12bf0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
12c00 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
12c10 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
12c20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
12c30 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
12c40 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
12c50 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
12c60 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
12c70 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
12c80 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
12c90 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
12ca0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
12cb0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
12cc0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
12cd0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12ce0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12cf0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
12d00 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
12d10 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
12d20 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
12d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
12d40 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
12d50 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
12d60 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
12d70 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
12d80 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
12d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12da0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
12db0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
12dc0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
12dd0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12de0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12df0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
12e00 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
12e10 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
12e20 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
12e30 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
12e40 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
12e50 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
12e60 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
12e70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12e80 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
12e90 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
12ea0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
12eb0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
12ec0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
12ed0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
12ee0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
12ef0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
12f00 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
12f10 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
12f20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12f30 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
12f40 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
12f50 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
12f60 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
12f70 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
12f80 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
12f90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12fa0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12fb0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
12fc0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
12fd0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
12fe0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
12ff0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
13000 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
13010 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
13020 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
13030 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
13040 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
13050 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
13060 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
13070 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
13080 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
13090 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
130a0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
130b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
130c0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
130d0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
130e0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
130f0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
13100 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
13110 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
13120 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
13130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
13140 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
13150 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
13160 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
13170 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
13180 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
13190 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
131a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
131b0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
131c0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
131d0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
131e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
131f0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
13200 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
13210 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
13220 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
13230 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
13240 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
13250 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
13260 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
13270 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
13280 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
13290 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
132a0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
132b0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
132c0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
132d0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
132e0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
132f0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
13300 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
13310 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
13320 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
13330 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
13340 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
13350 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
13360 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
13370 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
13380 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
13390 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
133a0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
133b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
133c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
133d0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
133e0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
133f0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
13400 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
13410 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
13420 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
13430 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
13440 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
13450 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
13460 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
13470 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
13480 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
13490 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
134a0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
134b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
134c0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
134d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
134e0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
134f0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
13500 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
13510 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
13520 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
13530 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
13540 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
13550 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
13560 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
13570 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
13580 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
13590 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
135a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
135b0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
135c0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
135d0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
135e0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
135f0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
13600 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
13610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
13620 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
13630 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
13640 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
13650 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
13660 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
13670 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
13680 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
13690 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
136a0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
136b0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
136c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
136d0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
136e0 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
136f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
13700 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
13710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13720 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
13730 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
13740 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
13750 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
13760 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
13770 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
13780 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
13790 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
137a0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
137b0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
137c0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
137d0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
137e0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
137f0 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
13800 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
13810 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
13820 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
13830 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
13840 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
13850 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
13860 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
13870 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
13880 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
13890 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
138a0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
138b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
138c0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
138d0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
138e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
138f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13900 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13910 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
13920 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
13930 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
13940 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
13950 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
13960 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
13970 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13980 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
13990 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
139a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
139b0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
139c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
139d0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
139e0 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
139f0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
13a00 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
13a10 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
13a20 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
13a30 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
13a40 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
13a50 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
13a60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
13a70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
13a80 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
13a90 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
13aa0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13ab0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13ac0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
13ad0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
13ae0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
13af0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
13b00 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
13b10 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
13b20 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
13b30 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
13b40 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
13b50 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
13b60 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
13b70 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
13b80 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
13b90 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
13ba0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
13bb0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
13bc0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
13bd0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
13be0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
13bf0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
13c00 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
13c10 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13c20 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
13c30 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
13c40 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
13c50 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
13c60 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
13c70 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
13c80 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
13c90 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
13ca0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
13cb0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
13cc0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
13cd0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13ce0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
13cf0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
13d00 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
13d10 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
13d20 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
13d30 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
13d40 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
13d50 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
13d60 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
13d70 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
13d80 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
13d90 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
13da0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13db0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
13dc0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
13dd0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
13de0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
13df0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
13e00 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
13e10 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
13e20 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
13e30 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
13e40 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
13e50 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
13e60 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
13e70 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
13e80 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
13e90 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
13ea0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
13eb0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
13ec0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
13ed0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
13ee0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
13ef0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
13f00 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
13f10 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
13f20 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13f30 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
13f40 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
13f50 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
13f60 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
13f70 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
13f80 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
13f90 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
13fa0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
13fb0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
13fc0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
13fd0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
13fe0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
13ff0 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
14000 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
14010 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
14020 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
14030 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
14040 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
14050 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
14060 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
14070 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
14080 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
14090 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
140a0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
140b0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
140c0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
140d0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
140e0 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
140f0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
14100 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
14110 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
14120 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
14130 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
14140 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
14150 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
14160 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
14170 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
14180 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
14190 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
141a0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
141b0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
141c0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
141d0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
141e0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
141f0 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
14200 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
14210 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
14220 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
14230 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
14240 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
14250 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
14260 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
14270 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
14280 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
14290 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
142a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
142b0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
142c0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
142d0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
142e0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
142f0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
14300 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
14310 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
14320 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
14330 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
14340 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
14350 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
14360 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
14370 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
14380 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
14390 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
143a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
143b0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
143c0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
143d0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
143e0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
143f0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
14400 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
14410 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
14420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14430 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
14440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14450 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
14460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
14470 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
14480 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
14490 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
144a0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
144b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
144c0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
144d0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
144e0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
144f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
14500 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
14510 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
14520 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
14530 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
14540 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
14550 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
14560 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
14570 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
14580 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
14590 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
145a0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
145b0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
145c0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
145d0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
145e0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
145f0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
14600 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
14610 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
14620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
14630 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
14640 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
14650 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14660 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
14670 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
14680 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
14690 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
146a0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
146b0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
146c0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
146d0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
146e0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
146f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
14700 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
14710 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14720 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
14730 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
14740 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
14750 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
14760 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
14770 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
14780 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
14790 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
147a0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
147b0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
147c0 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
147d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
147e0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
147f0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
14800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
14810 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
14820 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
14830 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
14840 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
14850 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
14860 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
14870 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
14880 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
14890 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
148a0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
148b0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
148c0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
148d0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
148e0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
148f0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
14900 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
14910 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
14920 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
14930 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
14940 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
14950 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
14960 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
14970 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
14980 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
14990 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
149a0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
149b0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
149c0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
149d0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
149e0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
149f0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
14a00 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
14a10 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
14a20 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
14a30 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
14a40 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
14a50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
14a60 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
14a70 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
14a80 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
14a90 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
14aa0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
14ab0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
14ac0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
14ad0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
14ae0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
14af0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
14b00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
14b10 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
14b20 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
14b30 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
14b40 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
14b50 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
14b60 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
14b70 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
14b80 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
14b90 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
14ba0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
14bb0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
14bc0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
14bd0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
14be0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
14bf0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
14c00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
14c10 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
14c20 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
14c30 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
14c40 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
14c50 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
14c60 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
14c70 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
14c80 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
14c90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
14ca0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
14cb0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
14cc0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
14cd0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14ce0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
14cf0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
14d00 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14d10 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
14d20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
14d30 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
14d40 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14d50 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
14d60 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
14d70 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
14d80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14d90 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
14da0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
14db0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
14dc0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
14dd0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
14de0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
14df0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14e00 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
14e10 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
14e20 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
14e30 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
14e40 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
14e50 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
14e60 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
14e70 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
14e80 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
14e90 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
14ea0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
14eb0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
14ec0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
14ed0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14ee0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14ef0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
14f00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14f10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
14f20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
14f30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
14f40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
14f50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14f60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
14f70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14f80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
14f90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14fa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
14fb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14fc0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
14fd0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
14fe0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
14ff0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
15000 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
15010 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
15020 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
15030 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
15040 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
15050 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
15060 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
15070 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
15080 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
15090 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
150a0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
150b0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
150c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
150d0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
150e0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
150f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
15100 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
15110 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
15120 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
15130 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
15140 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
15150 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
15160 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
15170 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
15180 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
15190 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
151a0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
151b0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
151c0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
151d0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
151e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
151f0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
15200 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
15210 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
15220 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
15230 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
15240 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
15250 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
15260 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
15270 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
15280 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
15290 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
152a0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
152b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
152c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
152d0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
152e0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
152f0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
15300 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
15310 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
15320 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
15330 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
15340 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
15350 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
15360 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
15370 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
15380 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
15390 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
153a0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
153b0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
153c0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
153d0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
153e0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
153f0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
15400 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
15410 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
15420 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
15430 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
15440 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
15450 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
15460 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
15470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
15480 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
15490 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
154a0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
154b0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
154c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
154d0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
154e0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
154f0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
15500 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
15510 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
15520 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
15530 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
15540 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
15550 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
15560 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
15570 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
15580 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
15590 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
155a0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
155b0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
155c0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
155d0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
155e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
155f0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
15600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15610 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
15620 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
15630 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
15640 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
15650 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
15660 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
15670 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
15680 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
15690 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
156a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
156b0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
156c0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
156d0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
156e0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
156f0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
15700 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
15710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15720 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
15730 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
15740 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
15750 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
15760 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
15770 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
15780 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
15790 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
157a0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
157b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
157c0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
157d0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
157e0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
157f0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
15800 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74  **.** ^(In sqlit
15810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
15820 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
15830 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
15840 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
15850 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
15860 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
15870 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
15880 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
15890 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
158a0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
158b0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
158c0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
158d0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
158e0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
158f0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
15900 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
15910 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
15920 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
15930 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
15940 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
15950 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
15960 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
15970 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
15980 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15990 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
159a0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
159b0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
159c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
159d0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
159e0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
159f0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
15a00 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
15a10 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
15a20 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
15a30 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
15a40 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
15a50 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
15a60 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
15a70 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
15a80 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
15a90 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
15aa0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
15ab0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
15ac0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
15ad0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
15ae0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
15af0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
15b00 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
15b10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
15b20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
15b30 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
15b40 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
15b50 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
15b60 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
15b70 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
15b80 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
15b90 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
15ba0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
15bb0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
15bc0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
15bd0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
15be0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
15bf0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
15c00 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
15c10 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
15c20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
15c30 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
15c40 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
15c50 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
15c60 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
15c70 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
15c80 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
15c90 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
15ca0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
15cb0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
15cc0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
15cd0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
15ce0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
15cf0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
15d00 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
15d10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
15d20 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
15d30 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
15d40 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
15d50 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
15d60 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
15d70 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
15d80 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
15d90 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
15da0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
15db0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
15dc0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
15dd0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
15de0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
15df0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
15e00 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
15e10 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
15e20 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
15e30 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
15e40 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
15e50 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
15e60 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
15e70 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
15e80 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
15e90 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15ea0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15eb0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
15ec0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
15ed0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
15ee0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15ef0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
15f00 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
15f10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
15f20 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
15f30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15f40 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
15f50 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
15f60 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
15f70 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
15f80 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
15f90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
15fa0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
15fb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
15fc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
15fd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15fe0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
15ff0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
16000 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
16010 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
16020 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
16030 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
16040 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
16050 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
16060 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16070 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
16080 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
16090 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
160a0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
160b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
160c0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
160d0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
160e0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
160f0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
16100 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
16110 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
16120 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
16130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16140 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
16150 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
16160 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
16170 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
16180 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16190 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
161a0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
161b0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
161c0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
161d0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
161e0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
161f0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
16200 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
16210 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
16220 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
16230 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
16240 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
16250 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
16260 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
16270 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
16280 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
16290 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
162a0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
162b0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
162c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
162d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
162e0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
162f0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
16300 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
16310 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
16320 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
16330 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
16340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
16360 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
16370 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
16380 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
16390 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
163a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
163b0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
163c0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
163d0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
163e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
163f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
16400 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
16410 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
16420 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
16430 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
16440 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
16450 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
16460 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
16470 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
16480 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
16490 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
164a0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
164b0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
164c0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
164d0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
164e0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
164f0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
16500 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
16510 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
16520 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
16530 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
16540 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
16560 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
16570 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
16580 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
16590 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
165a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
165b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
165c0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
165d0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
165e0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
165f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
16600 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
16610 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
16620 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
16630 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
16640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16650 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
16660 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
16670 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
16680 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
16690 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
166a0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
166b0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
166c0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
166d0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
166e0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
166f0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
16700 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
16710 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16720 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
16730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
16740 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
16750 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
16760 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
16770 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
16780 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
16790 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
167a0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
167b0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
167c0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
167d0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
167e0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
167f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
16800 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
16810 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
16820 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
16830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16840 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
16850 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
16860 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
16870 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
16880 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
16890 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
168a0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
168b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
168c0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
168d0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
168e0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
168f0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
16900 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
16910 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
16920 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
16930 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
16940 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
16950 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
16960 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
16970 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
16980 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
16990 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
169a0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
169b0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
169c0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
169d0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
169e0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
169f0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
16a00 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
16a10 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
16a20 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
16a30 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
16a40 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
16a50 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
16a60 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
16a70 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
16a80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
16a90 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
16aa0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
16ab0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
16ac0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
16ad0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
16ae0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
16af0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
16b00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16b10 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
16b20 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
16b30 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
16b40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
16b50 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
16b60 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
16b70 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
16b80 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
16b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16ba0 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
16bb0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
16bc0 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
16bd0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16be0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16bf0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
16c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
16c10 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
16c20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
16c30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
16c40 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
16c50 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
16c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
16c70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16c80 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
16c90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16ca0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16cb0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
16cc0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
16cd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
16ce0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
16cf0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
16d00 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
16d10 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
16d20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
16d30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16d40 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
16d50 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
16d60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16d70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16d80 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
16d90 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
16da0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
16db0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
16dc0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
16dd0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
16de0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
16df0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
16e00 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
16e10 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
16e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
16e30 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
16e40 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
16e50 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
16e60 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
16e70 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
16e80 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
16e90 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
16ea0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16eb0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
16ec0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
16ed0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
16ee0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
16ef0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
16f00 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
16f10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
16f20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
16f30 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
16f40 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
16f50 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
16f60 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
16f70 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
16f80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
16f90 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
16fa0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
16fb0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
16fc0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
16fd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
16fe0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
16ff0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
17000 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
17010 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
17020 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
17030 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
17040 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
17050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17060 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
17070 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
17080 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
17090 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
170a0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
170b0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
170c0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
170d0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
170e0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
170f0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
17100 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
17110 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
17120 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
17130 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
17140 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
17150 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
17160 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
17170 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
17180 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
17190 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
171a0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
171b0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
171c0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
171d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
171e0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
171f0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
17200 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
17210 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
17220 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
17230 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
17240 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
17250 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
17260 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
17270 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
17280 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
17290 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
172a0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
172b0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
172c0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
172d0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
172e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
172f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
17300 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
17310 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
17320 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
17330 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
17340 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
17350 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
17360 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
17370 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
17380 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
17390 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
173a0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
173b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
173c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
173d0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
173e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
173f0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
17400 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
17410 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
17420 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
17430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17440 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
17450 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
17460 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
17470 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
17480 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
17490 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
174a0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
174b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
174c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
174d0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
174e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
174f0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
17500 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
17510 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
17520 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
17530 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
17540 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
17550 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
17560 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17570 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
17580 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
17590 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
175a0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
175b0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
175c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
175d0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
175e0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
175f0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
17600 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
17610 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
17620 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
17630 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
17640 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
17650 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
17660 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17670 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
17680 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
17690 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
176a0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
176b0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
176c0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
176d0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
176e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
176f0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
17700 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
17710 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
17720 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
17730 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
17740 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17750 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
17760 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
17770 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
17780 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
17790 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
177a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
177b0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
177c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
177d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
177e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
177f0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
17800 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
17810 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
17820 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
17830 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
17840 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
17850 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
17860 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
17870 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17880 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
17890 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
178a0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
178b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
178c0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
178d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
178e0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
178f0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
17900 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
17910 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
17920 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
17930 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
17940 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
17950 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
17960 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
17970 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
17980 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
17990 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
179a0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
179b0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
179c0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
179d0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
179e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
179f0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
17a00 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
17a10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
17a20 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
17a30 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
17a40 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
17a50 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
17a60 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
17a70 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
17a80 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
17a90 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
17aa0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
17ab0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
17ac0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
17ad0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
17ae0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
17af0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
17b00 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
17b10 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
17b20 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
17b30 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
17b40 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
17b50 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
17b60 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
17b70 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
17b80 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
17b90 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
17ba0 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
17bb0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
17bc0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
17bd0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
17be0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
17bf0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
17c00 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
17c10 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
17c20 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
17c30 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
17c40 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
17c50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
17c60 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
17c70 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
17c80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
17c90 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
17ca0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17cb0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
17cc0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
17cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
17ce0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
17cf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
17d00 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
17d10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17d20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
17d30 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
17d40 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
17d50 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
17d60 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
17d70 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
17d80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
17d90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
17da0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
17db0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
17dc0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
17dd0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
17de0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
17df0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
17e00 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
17e10 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
17e20 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
17e30 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
17e40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17e50 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
17e60 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
17e70 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
17e80 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
17e90 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
17ea0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
17eb0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
17ec0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
17ed0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
17ee0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
17ef0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
17f00 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
17f10 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
17f20 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
17f30 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
17f40 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
17f50 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
17f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
17f70 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
17f80 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
17f90 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
17fa0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
17fb0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
17fc0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
17fd0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
17fe0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
17ff0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
18000 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
18010 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
18020 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
18030 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
18040 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
18050 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
18060 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
18070 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
18080 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18090 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
180a0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
180b0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
180c0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
180d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
180e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
180f0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
18100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18110 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
18120 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
18130 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
18140 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
18150 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
18160 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
18170 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
18180 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
18190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
181a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
181b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
181c0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
181d0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
181e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
181f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
18200 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
18210 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
18220 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
18230 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
18240 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
18250 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
18260 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
18270 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
18280 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
18290 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
182a0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
182b0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
182c0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
182d0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
182e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
182f0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
18300 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
18310 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
18320 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
18330 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
18340 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
18350 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
18360 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
18370 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18380 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
18390 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
183a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
183b0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
183c0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
183d0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
183e0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
183f0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
18400 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
18410 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
18420 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
18430 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
18440 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
18450 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
18460 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
18470 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
18480 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
18490 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
184a0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
184b0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
184c0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
184d0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
184e0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
184f0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
18500 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
18510 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
18520 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
18530 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
18540 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
18550 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
18560 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
18570 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
18580 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
18590 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
185a0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
185b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
185c0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
185d0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
185e0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
185f0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
18600 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
18610 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
18620 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
18630 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
18640 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
18650 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
18660 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
18670 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
18680 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
18690 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
186a0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
186b0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
186c0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
186d0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
186e0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
186f0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
18700 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
18710 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
18720 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
18730 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
18740 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
18750 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
18760 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
18770 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
18780 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
18790 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
187a0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
187b0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
187c0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
187d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
187e0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
187f0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
18800 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
18810 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
18820 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
18830 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
18840 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
18850 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
18860 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
18870 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
18880 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
18890 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
188a0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
188b0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
188c0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
188d0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
188e0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
188f0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
18900 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
18910 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
18920 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
18930 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
18940 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
18950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18960 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
18970 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
18980 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18990 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
189a0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
189b0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
189c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
189d0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
189e0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
189f0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
18a00 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
18a10 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
18a20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18a30 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
18a40 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
18a50 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
18a60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18a70 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
18a80 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
18a90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
18aa0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
18ab0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18ac0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
18ad0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
18ae0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
18af0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
18b00 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
18b10 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
18b20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
18b30 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
18b40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18b50 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
18b60 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
18b70 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
18b80 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
18b90 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
18ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18bb0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
18bc0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
18bd0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
18be0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
18bf0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
18c00 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
18c10 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
18c20 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
18c30 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
18c40 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
18c50 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
18c60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18c70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
18c80 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
18c90 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
18ca0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
18cb0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
18cc0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
18cd0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
18ce0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
18cf0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
18d00 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
18d10 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
18d20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
18d30 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
18d40 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
18d50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18d60 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
18d70 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
18d80 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
18d90 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
18da0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18db0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
18dc0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
18dd0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
18de0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18df0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
18e00 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
18e10 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
18e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
18e30 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
18e40 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
18e50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18e60 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
18e70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
18e80 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
18e90 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
18ea0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
18eb0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
18ec0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
18ed0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
18ee0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
18ef0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
18f00 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
18f10 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
18f20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18f30 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
18f40 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
18f50 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
18f60 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
18f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18f80 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
18f90 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
18fa0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
18fb0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
18fc0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
18fd0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
18fe0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
18ff0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
19000 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
19010 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
19020 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
19030 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
19040 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
19060 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
19070 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
19080 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
19090 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
190a0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
190b0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
190c0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
190d0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
190e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
190f0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
19100 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
19110 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
19120 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
19130 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
19140 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
19150 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
19160 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
19170 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
19180 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
19190 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
191a0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
191b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
191c0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
191d0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
191e0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
191f0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
19200 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
19210 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
19220 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
19230 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
19240 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
19250 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
19260 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
19270 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
19280 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
19290 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
192a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
192b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
192c0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
192d0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
192e0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
192f0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
19300 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
19310 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19320 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
19330 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
19340 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
19350 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
19360 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
19370 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
19380 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
19390 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
193a0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
193b0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
193c0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
193d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
193e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
193f0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
19400 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
19410 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
19420 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19430 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
19440 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
19450 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
19460 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19470 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19480 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
19490 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
194a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
194b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
194c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
194d0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
194e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
194f0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19500 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19510 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
19520 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
19530 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19540 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19550 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19560 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
19570 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
19580 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
19590 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
195a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
195b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
195c0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
195d0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
195e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
195f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19600 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
19610 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
19620 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19630 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19650 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
19660 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
19670 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19680 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
196a0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
196b0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
196c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
196d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
196e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
196f0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
19700 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
19710 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19740 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
19750 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
19760 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19770 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19790 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
197a0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
197b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
197c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
197d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
197e0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
197f0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
19800 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19810 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19820 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19830 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
19840 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
19850 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
19860 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19870 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19880 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
19890 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
198a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
198b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
198c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
198d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
198e0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
198f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19900 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19910 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
19920 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
19930 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
19940 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19950 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19960 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
19970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
19980 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19990 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
199a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
199b0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
199c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
199d0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
199e0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
199f0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
19a00 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
19a10 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
19a20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19a30 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
19a40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19a50 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
19a60 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
19a70 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
19a80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19a90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19aa0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
19ab0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
19ac0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
19ad0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19ae0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19af0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
19b00 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
19b10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19b20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
19b30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19b40 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
19b50 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
19b60 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
19b70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19b80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19b90 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
19ba0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
19bb0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
19bc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19bd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19be0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
19bf0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
19c00 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
19c10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19c30 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
19c40 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
19c50 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
19c60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
19c80 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
19c90 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
19ca0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19cb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19cd0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
19ce0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
19cf0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
19d00 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
19d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19d20 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
19d30 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
19d40 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
19d50 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
19d70 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
19d80 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
19d90 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
19da0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
19db0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
19dc0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
19dd0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
19de0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
19df0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
19e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
19e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19e20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
19e30 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
19e40 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
19e50 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
19e60 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
19e70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19e80 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
19e90 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
19ea0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
19eb0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
19ec0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
19ed0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
19ee0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
19ef0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
19f00 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19f10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
19f20 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
19f30 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
19f40 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
19f50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
19f60 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
19f70 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
19f80 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
19f90 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
19fa0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
19fb0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
19fc0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
19fd0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
19fe0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
19ff0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1a000 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1a010 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1a020 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1a030 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1a040 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1a050 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1a060 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1a070 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1a080 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1a090 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1a0a0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1a0b0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1a0c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1a0d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1a0e0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1a0f0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1a100 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1a110 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1a120 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1a130 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1a140 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1a150 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1a160 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1a170 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1a180 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1a190 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1a1a0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1a1b0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1a1c0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1a1d0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1a1e0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1a1f0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1a200 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1a210 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1a220 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1a230 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1a240 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1a250 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1a260 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1a270 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1a280 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1a290 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1a2a0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1a2b0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1a2c0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1a2d0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1a2e0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1a2f0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1a300 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1a310 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1a320 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1a330 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1a340 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1a350 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1a360 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1a370 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1a380 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1a390 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1a3a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1a3b0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1a3c0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1a3d0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1a3e0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1a3f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1a400 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1a410 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a420 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1a430 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1a440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a450 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a460 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1a470 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1a480 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1a490 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1a4a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1a4b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1a4c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1a4d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1a4e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1a4f0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1a500 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a510 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1a520 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1a530 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1a540 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1a550 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1a560 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1a570 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1a580 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1a590 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1a5a0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1a5b0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1a5c0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1a5d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1a5e0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1a5f0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1a600 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1a610 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1a620 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1a630 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1a640 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1a650 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1a660 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1a670 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1a680 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1a690 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1a6a0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1a6b0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1a6c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1a6d0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1a6e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1a6f0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1a700 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1a710 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1a720 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1a730 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1a740 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1a750 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1a760 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1a770 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1a780 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1a790 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1a7a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1a7b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1a7c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1a7d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1a7e0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1a7f0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1a800 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1a810 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1a820 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1a830 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1a840 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1a850 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1a860 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1a870 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1a880 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1a890 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a8a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1a8b0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1a8c0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1a8d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1a8e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1a8f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1a900 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1a910 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1a920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1a930 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1a940 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1a950 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1a960 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1a970 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1a980 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1a990 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1a9a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a9b0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1a9c0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1a9d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1a9e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a9f0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1aa00 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f  atabase file who
1aa10 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e  se name is given
1aa20 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   by the.** filen
1aa30 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1aa40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1aa50 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1aa60 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1aa70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1aa80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1aa90 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1aaa0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1aab0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1aac0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1aad0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1aae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1aaf0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1ab00 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1ab10 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1ab20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1ab30 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1ab40 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1ab50 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1ab60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1ab70 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1ab80 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1ab90 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1aba0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1abb0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1abc0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1abd0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1abe0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1abf0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1ac00 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1ac10 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1ac20 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1ac30 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1ac40 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1ac50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1ac60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1ac70 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1ac80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1ac90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1aca0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1acb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1acc0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1acd0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1ace0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1acf0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1ad00 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1ad10 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1ad20 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1ad30 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1ad40 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1ad50 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1ad60 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1ad70 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1ad80 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1ad90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1ada0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1adb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1adc0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1add0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1ade0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1adf0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1ae00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1ae10 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1ae20 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1ae30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1ae40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1ae50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1ae60 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1ae70 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1ae80 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1ae90 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1aea0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1aeb0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1aec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1aed0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1aee0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1aef0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1af00 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1af10 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1af20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1af30 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1af40 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1af50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1af60 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1af70 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1af80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1af90 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
1afa0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
1afb0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
1afc0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
1afd0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
1afe0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
1aff0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
1b000 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1b010 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1b020 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
1b030 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  .** and/or [SQLI
1b040 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1b050 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  ACHE] flags:)^.*
1b060 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1b070 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1b080 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1b090 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1b0a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1b0b0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1b0c0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1b0d0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1b0e0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1b0f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1b100 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1b110 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1b120 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1b130 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1b140 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1b150 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1b160 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1b170 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1b180 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1b190 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1b1a0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1b1b0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1b1c0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1b1d0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1b1e0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1b1f0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1b200 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1b210 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1b220 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1b230 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1b240 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1b250 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1b260 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1b270 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1b280 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1b290 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73  , and is creates
1b2a0 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65   it if.** it doe
1b2b0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
1b2c0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
1b2d0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
1b2e0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
1b2f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1b300 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1b310 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
1b320 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1b330 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1b340 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b350 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1b360 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1b370 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1b380 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f  n above or one o
1b390 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  f the combinatio
1b3a0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63  ns shown above c
1b3b0 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20  ombined.** with 
1b3c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1b3d0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1b3e0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1b3f0 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  X],.** [SQLITE_O
1b400 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1b410 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1b420 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1b430 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65  E] flags,.** the
1b440 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1b450 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1b460 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
1b470 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1b480 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1b490 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1b4a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1b4b0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1b4c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1b4d0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1b4e0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1b4f0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1b500 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1b510 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1b520 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
1b530 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1b540 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1b550 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1b560 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1b570 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1b580 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1b590 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1b5a0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1b5b0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1b5c0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1b5d0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1b5e0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1b5f0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
1b600 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1b610 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
1b620 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1b630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
1b640 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
1b650 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
1b660 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
1b670 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1b680 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
1b690 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1b6a0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1b6b0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1b6c0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
1b6d0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1b6e0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1b6f0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1b700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b710 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
1b720 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
1b730 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
1b740 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
1b750 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  led..**.** ^If t
1b760 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1b770 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1b780 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1b790 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1b7a0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1b7b0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1b7c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1b7d0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1b7e0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1b7f0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1b800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b810 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1b820 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1b830 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1b840 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1b850 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1b860 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1b870 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1b880 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1b890 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1b8a0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1b8b0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1b8c0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1b8d0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1b8e0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1b8f0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1b900 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1b910 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1b920 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1b930 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1b940 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1b950 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1b960 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1b970 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1b980 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1b990 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1b9a0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1b9b0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1b9c0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1b9d0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1b9e0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1b9f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ba00 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1ba10 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1ba20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ba30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ba40 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ba50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1ba60 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1ba70 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1ba80 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1ba90 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1baa0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1bab0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1bac0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1bad0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bae0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1baf0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1bb00 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1bb10 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1bb20 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1bb30 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1bb40 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1bb50 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1bb60 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1bb70 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1bb80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1bb90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1bba0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1bbb0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1bbc0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1bbd0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1bbe0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1bbf0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1bc00 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1bc10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1bc20 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1bc30 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1bc40 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1bc50 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1bc60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
1bc70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1bc80 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
1bc90 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1bca0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1bcb0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1bcc0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1bcd0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1bce0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1bcf0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1bd00 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
1bd10 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
1bd20 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1bd30 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
1bd40 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1bd50 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1bd60 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1bd70 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1bd80 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
1bd90 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
1bda0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1bdb0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1bdc0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1bdd0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
1bde0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1bdf0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1be00 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
1be10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1be20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
1be30 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
1be40 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
1be50 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
1be60 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1be70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
1be80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
1be90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bea0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1beb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1bec0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
1bed0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
1bee0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1bef0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1bf00 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1bf10 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1bf20 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
1bf30 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
1bf40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1bf50 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1bf60 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
1bf70 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1bf80 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1bf90 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1bfa0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
1bfb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1bfc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
1bfd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
1bfe0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
1bff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1c000 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
1c010 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
1c020 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
1c030 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1c040 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
1c050 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1c060 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
1c070 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1c080 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1c090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1c0a0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1c0b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1c0c0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1c0d0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1c0e0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1c0f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1c100 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
1c110 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
1c120 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1c130 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1c140 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1c150 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c160 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1c170 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
1c180 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1c190 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1c1a0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1c1b0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1c1c0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1c1d0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1c1e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1c1f0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1c200 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1c210 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
1c220 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1c230 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
1c240 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
1c250 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
1c260 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
1c270 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
1c280 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1c290 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
1c2a0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
1c2b0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
1c2c0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
1c2d0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1c2e0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
1c2f0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
1c300 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
1c310 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
1c320 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
1c330 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
1c340 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
1c350 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
1c360 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
1c370 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
1c380 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
1c390 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1c3a0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
1c3b0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
1c3c0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
1c3d0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1c3e0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
1c3f0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
1c400 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
1c410 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1c420 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
1c430 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
1c440 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
1c450 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
1c460 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
1c470 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
1c480 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
1c490 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
1c4a0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
1c4b0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
1c4c0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
1c4d0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
1c4e0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
1c4f0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
1c500 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
1c510 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
1c520 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
1c530 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
1c540 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1c550 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1c560 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1c570 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
1c580 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1c590 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1c5a0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1c5b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1c5c0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1c5d0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1c5e0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1c5f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
1c600 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1c610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1c620 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1c630 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1c640 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1c650 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1c660 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1c670 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1c680 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1c690 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1c6a0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1c6b0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1c6c0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1c6d0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1c6e0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1c6f0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1c700 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1c710 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1c720 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1c730 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1c740 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1c750 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1c760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c770 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1c780 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1c790 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1c7a0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1c7b0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1c7c0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1c7d0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1c7e0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1c7f0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1c800 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1c810 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1c820 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1c830 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1c840 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1c850 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1c860 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1c870 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1c880 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1c890 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1c8a0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1c8b0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1c8c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1c8d0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1c8e0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1c8f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1c900 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1c910 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1c920 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1c930 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1c940 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1c950 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1c960 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1c970 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1c980 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
1c990 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1c9a0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1c9b0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1c9c0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1c9d0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1c9e0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1c9f0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1ca00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1ca10 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1ca20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1ca30 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1ca40 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1ca50 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1ca60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1ca70 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1ca80 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1ca90 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1caa0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1cab0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1cac0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1cad0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1cae0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1caf0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1cb00 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1cb10 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1cb20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1cb30 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1cb40 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1cb50 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
1cb60 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
1cb70 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
1cb80 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
1cb90 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
1cba0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
1cbb0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1cbc0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
1cbd0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
1cbe0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
1cbf0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
1cc00 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
1cc10 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1cc20 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1cc30 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
1cc40 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
1cc50 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1cc60 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1cc70 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1cc80 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1cc90 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1cca0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
1ccb0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
1ccc0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1ccd0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
1cce0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
1ccf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
1cd00 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
1cd10 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
1cd20 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
1cd30 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
1cd40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
1cd50 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
1cd60 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
1cd70 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
1cd80 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
1cd90 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
1cda0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
1cdb0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
1cdc0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
1cdd0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1cde0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1cdf0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1ce00 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1ce10 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1ce20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1ce30 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1ce40 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1ce50 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1ce60 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ce70 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1ce80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1ce90 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
1cea0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1ceb0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1cec0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1ced0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1cee0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1cef0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1cf00 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1cf10 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1cf20 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1cf30 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1cf40 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1cf50 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1cf60 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1cf70 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1cf80 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1cf90 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1cfa0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1cfb0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1cfc0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1cfd0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1cfe0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1cff0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1d000 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1d010 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1d020 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d030 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1d040 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1d050 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1d060 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1d070 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1d080 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1d090 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1d0a0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1d0b0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1d0c0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1d0d0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1d0e0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1d0f0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1d100 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1d110 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1d120 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1d130 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1d140 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1d150 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1d160 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1d170 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
1d180 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
1d190 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
1d1a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1d1b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
1d1c0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1d1d0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
1d1e0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
1d1f0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
1d200 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
1d210 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1d220 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
1d230 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
1d240 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1d250 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
1d260 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
1d270 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1d280 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
1d290 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
1d2a0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
1d2b0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
1d2c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d2d0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1d2e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d2f0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1d300 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1d310 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
1d320 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
1d330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d340 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1d350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d360 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1d370 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d380 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
1d390 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d3a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1d3b0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
1d3c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1d3d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1d3e0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
1d3f0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
1d400 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1d410 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
1d420 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1d430 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1d440 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1d450 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1d460 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1d470 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1d480 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d490 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
1d4a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d4b0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
1d4c0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
1d4d0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
1d4e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1d4f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1d500 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1d510 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d520 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d530 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1d540 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1d550 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
1d560 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1d570 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1d580 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d590 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d5a0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1d5b0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1d5c0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1d5d0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1d5e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1d5f0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
1d600 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
1d610 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
1d620 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
1d630 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
1d640 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
1d650 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
1d660 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d670 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1d680 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
1d690 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d6a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1d6b0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
1d6c0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
1d6d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d6e0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
1d6f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d700 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
1d710 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
1d720 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
1d730 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  dd>.**.** ^(<dt>
1d740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1d750 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1d760 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d770 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1d780 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1d790 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
1d7a0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
1d7b0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
1d7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1d7d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
1d7e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
1d7f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d800 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
1d810 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
1d820 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
1d830 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
1d840 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1d850 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1d860 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1d870 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1d880 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
1d890 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
1d8a0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
1d8b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d8c0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
1d8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1d8e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d8f0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1d900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d910 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1d920 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
1d930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d940 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1d950 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1d960 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1d970 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
1d980 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1d990 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
1d9a0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
1d9b0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1d9c0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
1d9d0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
1d9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1d9f0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
1da00 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
1da10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1da20 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
1da30 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
1da40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1da50 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1da60 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
1da70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
1da80 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
1da90 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
1daa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
1dab0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
1dac0 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
1dad0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1dae0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
1daf0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
1db00 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
1db10 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
1db20 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1db30 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1db40 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1db50 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1db60 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1db70 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1db80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
1db90 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1dba0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
1dbb0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
1dbc0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
1dbd0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
1dbe0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
1dbf0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
1dc00 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1dc10 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
1dc20 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
1dc30 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
1dc40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
1dc50 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
1dc60 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
1dc70 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1dc80 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
1dc90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
1dca0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
1dcb0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
1dcc0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1dcd0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
1dce0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
1dcf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dd00 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
1dd10 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
1dd20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dd30 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
1dd40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
1dd50 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
1dd60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
1dd70 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1dd80 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1dd90 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1dda0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
1ddb0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1ddc0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
1ddd0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1dde0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
1ddf0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
1de00 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
1de10 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
1de20 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
1de30 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
1de40 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
1de50 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
1de60 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
1de70 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
1de80 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
1de90 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
1dea0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
1deb0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
1dec0 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
1ded0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
1dee0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
1def0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
1df00 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
1df10 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
1df20 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
1df30 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
1df40 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
1df50 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
1df60 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
1df70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
1df80 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
1df90 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
1dfa0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
1dfb0 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  r bytes..**.** ^
1dfc0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
1dfd0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
1dfe0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
1dff0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
1e000 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
1e010 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
1e020 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
1e030 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
1e040 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
1e050 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
1e060 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
1e070 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
1e080 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
1e090 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
1e0a0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
1e0b0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
1e0c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1e0d0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1e0e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e0f0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1e100 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1e110 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1e120 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
1e130 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1e140 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1e150 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
1e160 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1e170 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
1e180 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
1e190 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
1e1a0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
1e1b0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
1e1c0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
1e1d0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
1e1e0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
1e1f0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
1e200 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
1e210 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
1e220 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1e230 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
1e240 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
1e250 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
1e260 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
1e270 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
1e280 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
1e290 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
1e2a0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
1e2b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1e2c0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
1e2d0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1e2e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1e2f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1e300 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1e310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e320 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1e330 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1e340 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1e350 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1e360 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1e370 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1e380 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1e390 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1e3a0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1e3b0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1e3c0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
1e3d0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
1e3e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e3f0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
1e400 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
1e410 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1e420 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
1e430 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
1e440 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
1e450 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
1e460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e470 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
1e480 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
1e490 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
1e4a0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1e4b0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
1e4c0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1e4d0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
1e4e0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
1e4f0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
1e500 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
1e510 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
1e520 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1e530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1e540 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
1e550 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
1e560 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
1e570 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  gain..** </li>.*
1e580 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
1e590 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1e5a0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1e5b0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1e5c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1e5d0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1e5e0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1e5f0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1e600 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
1e610 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
1e620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1e630 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
1e640 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
1e650 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1e660 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
1e670 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
1e680 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
1e690 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1e6a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
1e6b0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
1e6c0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
1e6d0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1e6e0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1e6f0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1e700 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
1e710 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1e720 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1e730 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
1e740 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1e750 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
1e760 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
1e770 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
1e780 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
1e790 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
1e7a0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
1e7b0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
1e7c0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
1e7d0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
1e7e0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
1e7f0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
1e800 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
1e810 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
1e820 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
1e830 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
1e840 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
1e850 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
1e860 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
1e870 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
1e880 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
1e890 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
1e8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1e8b0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1e8c0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
1e8d0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
1e8e0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
1e8f0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
1e900 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
1e910 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
1e920 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
1e930 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
1e940 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
1e950 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
1e960 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
1e970 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
1e980 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e990 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
1e9a0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
1e9b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
1e9c0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32  ITE_ENABLE_STAT2
1e9d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1e9e0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
1e9f0 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c  ..** the .** </l
1ea00 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1ea10 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1ea20 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1ea30 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1ea40 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1ea50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ea60 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1ea70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1ea80 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1ea90 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1eaa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1eab0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1eac0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1ead0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1eae0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1eaf0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1eb00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1eb10 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1eb20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1eb30 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1eb40 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1eb50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1eb60 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1eb70 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1eb80 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1eb90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1eba0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1ebb0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1ebc0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1ebd0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1ebe0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1ebf0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1ec00 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1ec10 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1ec20 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1ec30 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1ec40 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1ec50 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1ec60 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1ec70 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1ec80 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1ec90 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1eca0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1ecb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ecc0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1ecd0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1ece0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1ecf0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1ed00 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1ed10 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1ed20 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1ed30 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1ed40 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1ed50 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1ed60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1ed70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1ed80 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1ed90 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1eda0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1edb0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1edc0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1edd0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1ede0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1edf0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1ee00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1ee10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1ee20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1ee30 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1ee40 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1ee50 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1ee60 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1ee70 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1ee80 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1ee90 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1eea0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1eeb0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1eec0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1eed0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1eee0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1eef0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1ef00 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1ef10 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1ef20 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1ef30 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1ef40 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1ef60 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1ef70 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1ef80 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1ef90 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1efa0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1efb0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1efc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1efd0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1efe0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1eff0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1f000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f010 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f020 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1f030 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f040 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1f050 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1f060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f070 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
1f080 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1f090 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
1f0a0 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
1f0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
1f0c0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
1f0d0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
1f0e0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
1f0f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f100 74 61 74 65 6d 65 6e 74 5d 20 58 20 69 73 20 5b  tatement] X is [
1f110 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1f120 74 20 61 6e 64 20 66 61 6c 73 65 20 28 7a 65 72  t and false (zer
1f130 6f 29 20 69 66 0a 2a 2a 20 58 20 69 73 20 61 6e  o) if.** X is an
1f140 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1f150 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 43  TE], [DELETE], C
1f160 52 45 41 54 45 2c 20 44 52 4f 50 2c 20 5b 41 4e  REATE, DROP, [AN
1f170 41 4c 59 5a 45 5d 2c 0a 2a 2a 20 5b 41 4c 54 45  ALYZE],.** [ALTE
1f180 52 5d 2c 20 6f 72 20 5b 52 45 49 4e 44 45 58 5d  R], or [REINDEX]
1f190 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 49   statement..** I
1f1a0 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1f1b0 69 6e 74 65 72 20 6f 72 20 61 6e 79 20 6f 74 68  inter or any oth
1f1c0 65 72 20 6b 69 6e 64 20 6f 66 20 73 74 61 74 65  er kind of state
1f1d0 6d 65 6e 74 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ment, including 
1f1e0 62 75 74 0a 2a 2a 20 6e 6f 74 20 6c 69 6d 69 74  but.** not limit
1f1f0 65 64 20 74 6f 20 5b 41 54 54 41 43 48 5d 2c 20  ed to [ATTACH], 
1f200 5b 44 45 54 41 43 48 5d 2c 20 5b 43 4f 4d 4d 49  [DETACH], [COMMI
1f210 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 20  T], [ROLLBACK], 
1f220 5b 52 45 4c 45 41 53 45 5d 2c 0a 2a 2a 20 5b 53  [RELEASE],.** [S
1f230 41 56 45 50 4f 49 4e 54 5d 2c 20 5b 50 52 41 47  AVEPOINT], [PRAG
1f240 4d 41 5d 2c 20 6f 72 20 5b 56 41 43 55 55 4d 5d  MA], or [VACUUM]
1f250 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 73   the result of s
1f260 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
1f270 6f 6e 6c 79 28 58 29 20 69 73 0a 2a 2a 20 75 6e  only(X) is.** un
1f280 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
1f290 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
1f2a0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
1f2b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1f2c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1f2d0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1f2e0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
1f2f0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
1f300 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1f310 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
1f320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
1f330 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1f340 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
1f350 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
1f360 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
1f370 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1f380 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
1f390 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
1f3a0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1f3b0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
1f3c0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
1f3d0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
1f3e0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
1f3f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
1f400 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
1f410 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
1f420 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
1f430 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
1f440 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
1f450 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1f460 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
1f470 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
1f480 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
1f490 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
1f4a0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
1f4b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1f4c0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
1f4d0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
1f4e0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
1f4f0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
1f500 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1f510 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
1f520 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
1f530 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
1f540 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
1f550 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
1f560 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
1f570 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
1f580 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1f590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
1f5a0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
1f5b0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
1f5c0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
1f5d0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
1f5e0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
1f5f0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
1f600 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
1f610 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1f620 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
1f630 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
1f640 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
1f650 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1f660 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
1f670 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1f680 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
1f690 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
1f6a0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
1f6b0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
1f6c0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
1f6d0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
1f6e0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
1f6f0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
1f700 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
1f710 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
1f720 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1f730 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
1f740 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1f750 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
1f760 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1f770 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1f780 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1f790 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1f7a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1f7b0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1f7c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
1f7d0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
1f7e0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
1f7f0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
1f800 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
1f810 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
1f820 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
1f830 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
1f840 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1f850 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1f860 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1f870 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1f880 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1f890 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1f8a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
1f8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1f8c0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
1f8d0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
1f8e0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
1f8f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1f900 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
1f910 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1f920 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
1f930 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
1f940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1f950 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
1f960 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1f970 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
1f980 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
1f990 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1f9a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1f9b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
1f9c0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
1f9d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
1f9e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
1f9f0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
1fa00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
1fa10 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
1fa20 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
1fa30 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
1fa40 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1fa50 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1fa60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1fa70 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1fa80 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
1fa90 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
1faa0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
1fab0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1fac0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
1fad0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1fae0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1faf0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1fb00 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1fb10 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1fb20 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
1fb30 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
1fb40 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
1fb50 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
1fb60 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
1fb70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1fb80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
1fb90 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1fba0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1fbb0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
1fbc0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
1fbd0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
1fbe0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
1fbf0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1fc00 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
1fc10 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
1fc20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
1fc30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
1fc40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
1fc50 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
1fc60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
1fc70 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
1fc80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1fc90 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
1fca0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1fcb0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
1fcc0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1fcd0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
1fce0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
1fcf0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
1fd00 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1fd10 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1fd20 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1fd30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1fd40 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1fd50 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1fd60 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1fd70 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1fd80 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1fd90 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1fda0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1fdb0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
1fdc0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
1fdd0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1fde0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1fdf0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
1fe00 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
1fe10 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
1fe20 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
1fe30 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
1fe40 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
1fe50 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
1fe60 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
1fe70 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
1fe80 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
1fe90 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
1fea0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
1feb0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
1fec0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
1fed0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
1fee0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
1fef0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
1ff00 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
1ff10 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
1ff20 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
1ff30 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
1ff40 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
1ff50 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
1ff60 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
1ff70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
1ff80 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
1ff90 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1ffa0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1ffb0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
1ffc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ffd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1ffe0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1fff0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
20000 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
20010 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
20020 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
20030 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
20040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20050 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
20060 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
20070 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
20080 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
20090 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
200a0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
200b0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
200c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
200d0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
200e0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
200f0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
20100 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
20110 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
20120 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
20130 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
20140 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
20150 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
20160 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
20170 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
20180 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
20190 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
201a0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
201b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
201c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
201d0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
201e0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
201f0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
20200 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
20210 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
20220 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
20230 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
20240 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
20250 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
20260 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
20270 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
20280 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
20290 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
202a0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
202b0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
202c0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
202d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
202e0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
202f0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
20300 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
20310 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
20320 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
20330 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
20340 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
20350 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
20360 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
20370 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
20380 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
20390 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
203a0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
203b0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
203c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
203d0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
203e0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
203f0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
20400 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
20410 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
20420 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
20430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
20440 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
20450 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
20460 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
20470 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
20480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20490 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
204a0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
204b0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
204c0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
204d0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
204e0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
204f0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
20500 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
20510 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
20520 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
20530 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
20540 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
20550 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
20560 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
20570 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
20580 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
20590 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
205a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
205b0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
205c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
205d0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
205e0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
205f0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
20600 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
20610 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
20620 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
20630 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
20640 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
20650 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
20660 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
20670 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
20680 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
20690 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
206a0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
206b0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
206c0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
206d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
206e0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
206f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20700 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
20710 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
20720 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
20730 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
20740 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
20750 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
20760 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
20770 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
20780 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
20790 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
207a0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
207b0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
207c0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
207d0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
207e0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
207f0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
20800 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
20810 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
20820 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
20830 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
20840 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
20850 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
20860 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
20870 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
20880 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
20890 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
208a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
208b0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
208c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
208d0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
208e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
208f0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
20900 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
20910 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
20920 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
20930 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
20940 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
20950 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
20960 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
20970 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
20980 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
20990 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
209a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
209b0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
209c0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
209d0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
209e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
209f0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
20a00 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
20a10 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
20a20 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
20a30 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
20a40 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
20a50 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
20a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
20a70 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
20a80 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
20a90 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
20aa0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
20ab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20ac0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
20ad0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
20ae0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
20af0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
20b00 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
20b10 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
20b20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
20b30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
20b40 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
20b50 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
20b60 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
20b70 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
20b80 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
20b90 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
20ba0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
20bb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
20bc0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
20bd0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20be0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
20bf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20c00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
20c10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
20c20 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
20c30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20c40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
20c50 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
20c60 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
20c70 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
20c80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20c90 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
20ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
20cb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20cc0 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
20cd0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
20ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20cf0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
20d00 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
20d10 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
20d20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
20d30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20d40 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
20d50 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
20d60 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
20d70 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
20d80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
20d90 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
20da0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
20db0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
20dc0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
20dd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
20de0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
20df0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
20e00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
20e10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20e20 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
20e30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
20e40 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
20e50 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
20e60 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
20e70 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
20e80 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
20e90 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
20ea0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
20eb0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
20ec0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20ed0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
20ee0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
20ef0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
20f00 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
20f10 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
20f20 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
20f30 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
20f40 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
20f50 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
20f60 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
20f70 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
20f80 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
20f90 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
20fa0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
20fb0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
20fc0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
20fd0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
20fe0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
20ff0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
21000 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
21010 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
21020 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
21030 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
21040 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
21050 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
21060 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
21070 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
21080 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
21090 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
210a0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
210b0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
210c0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
210d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
210e0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
210f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
21100 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21110 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
21120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21130 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
21140 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
21150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
21160 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
21170 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
21180 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
21190 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
211a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
211b0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
211c0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
211d0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
211e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
211f0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
21200 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
21210 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
21220 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
21230 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
21240 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
21250 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
21260 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
21270 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
21280 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
21290 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
212a0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
212b0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
212c0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
212d0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
212e0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
212f0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
21300 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
21310 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
21320 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
21330 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
21340 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
21350 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
21360 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
21370 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
21380 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
21390 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
213a0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
213b0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
213c0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
213d0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
213e0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
213f0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
21400 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
21410 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
21420 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
21430 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
21440 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
21450 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
21460 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
21470 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
21480 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
21490 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
214a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
214b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
214c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
214d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
214e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
214f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
21500 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
21510 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
21520 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
21530 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21540 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
21550 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
21560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21570 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
21580 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
21590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
215a0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
215b0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
215c0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
215d0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
215e0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
215f0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
21600 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
21610 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
21620 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
21630 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
21640 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
21650 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
21660 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
21670 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
21680 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
21690 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
216a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
216b0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
216c0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
216d0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
216e0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
216f0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
21700 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
21710 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
21720 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
21730 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21740 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
21750 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21760 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
21770 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
21780 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21790 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
217a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
217b0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
217c0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
217d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
217e0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
217f0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
21800 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
21810 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
21820 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
21830 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
21840 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
21850 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
21860 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
21870 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
21880 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
21890 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
218a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
218b0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
218c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
218d0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
218e0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
218f0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
21900 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
21910 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
21920 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
21930 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
21940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
21950 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
21960 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
21970 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
21980 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
21990 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
219a0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
219b0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
219c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
219d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
219e0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
219f0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
21a00 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
21a10 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
21a20 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
21a30 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
21a40 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21a50 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
21a60 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
21a70 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
21a80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
21a90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
21aa0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
21ab0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
21ac0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
21ad0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21ae0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
21af0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
21b00 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
21b10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
21b20 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
21b30 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
21b40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
21b50 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
21b60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
21b70 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
21b80 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
21b90 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
21ba0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
21bb0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
21bc0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
21bd0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
21be0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
21bf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21c00 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
21c10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
21c20 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
21c30 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
21c40 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
21c50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
21c60 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
21c70 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
21c80 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
21c90 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
21ca0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
21cb0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
21cc0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
21cd0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
21ce0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
21cf0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
21d00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21d10 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
21d20 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
21d30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
21d40 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
21d50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
21d60 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
21d70 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
21d80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21d90 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
21da0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
21db0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
21dc0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
21dd0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
21de0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
21df0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
21e00 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
21e10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
21e20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
21e30 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
21e40 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
21e50 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
21e60 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
21e70 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
21e80 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
21e90 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
21ea0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
21eb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21ec0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
21ed0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
21ee0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
21ef0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
21f00 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
21f10 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
21f20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
21f30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21f40 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
21f50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21f60 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
21f70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21f80 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
21f90 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
21fa0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
21fb0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
21fc0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
21fd0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
21fe0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
21ff0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
22000 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
22010 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
22020 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
22030 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
22040 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
22050 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
22060 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
22070 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
22080 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
22090 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
220a0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
220b0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
220c0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
220d0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
220e0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
220f0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
22100 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
22110 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
22120 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
22130 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
22140 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
22150 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
22160 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
22170 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
22180 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
22190 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
221a0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
221b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
221c0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
221d0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
221e0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
221f0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
22200 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
22210 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
22220 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
22230 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
22240 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
22250 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
22260 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
22270 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
22280 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22290 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
222a0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
222b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
222c0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
222d0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
222e0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
222f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
22300 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
22310 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
22320 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
22330 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
22340 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
22350 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
22360 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
22370 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
22380 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
22390 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
223a0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
223b0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
223c0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
223d0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
223e0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
223f0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
22400 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
22410 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
22420 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
22430 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
22440 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
22450 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
22460 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
22470 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
22480 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
22490 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
224a0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
224b0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
224c0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
224d0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
224e0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
224f0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
22500 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
22510 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
22520 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
22530 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
22540 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
22550 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
22560 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
22570 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
22580 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
22590 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
225a0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
225b0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
225c0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
225d0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
225e0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
225f0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
22600 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
22610 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
22620 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
22630 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
22640 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
22650 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
22660 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
22670 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
22680 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22690 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
226a0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
226b0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
226c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
226d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
226e0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
226f0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
22700 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
22710 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
22720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22730 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
22740 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
22750 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
22760 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22770 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
22780 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
22790 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
227a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
227b0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
227c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
227d0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
227e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
227f0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
22800 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22810 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
22820 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
22830 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
22840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
22850 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
22860 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
22870 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22880 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
22890 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
228a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
228b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
228c0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
228d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
228e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
228f0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
22900 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
22910 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
22920 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
22930 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
22940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
22950 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
22960 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
22970 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
22980 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
22990 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
229a0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
229b0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
229c0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
229d0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
229e0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
229f0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
22a00 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
22a10 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
22a20 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
22a30 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
22a40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
22a50 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
22a60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
22a70 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
22a80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
22a90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
22aa0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
22ab0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
22ac0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
22ad0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
22ae0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
22af0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
22b00 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
22b10 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
22b20 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
22b30 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
22b40 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
22b50 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
22b60 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
22b70 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
22b80 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
22b90 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
22ba0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
22bb0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
22bc0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
22bd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
22be0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
22bf0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
22c00 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
22c10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
22c20 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
22c30 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
22c40 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
22c50 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
22c60 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
22c70 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
22c80 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
22c90 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
22ca0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
22cb0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
22cc0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
22cd0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
22ce0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
22cf0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
22d00 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
22d10 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
22d20 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
22d30 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
22d40 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
22d50 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
22d60 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
22d70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
22d80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22d90 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
22da0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
22db0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22dc0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
22dd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22de0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
22df0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
22e00 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
22e10 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
22e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22e30 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
22e40 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
22e50 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
22e60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
22e70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22e80 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
22e90 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
22ea0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
22eb0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22ec0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
22ed0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
22ee0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
22ef0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
22f00 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
22f10 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
22f20 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
22f30 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
22f40 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
22f50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
22f60 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
22f70 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
22f80 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
22f90 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
22fa0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
22fb0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
22fc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22fd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
22fe0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
22ff0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
23000 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
23010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23020 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23030 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
23040 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
23050 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
23060 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
23070 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
23080 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
23090 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
230a0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
230b0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
230c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
230d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
230e0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
230f0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
23100 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
23110 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
23120 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
23130 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
23140 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
23150 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
23160 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
23170 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
23180 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
23190 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
231a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
231b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
231c0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
231d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
231e0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
231f0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
23200 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
23210 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
23220 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
23230 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
23240 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
23250 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
23260 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
23270 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
23280 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
23290 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
232a0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
232b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
232c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
232d0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
232e0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
232f0 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
23300 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
23310 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
23320 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
23330 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
23340 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
23350 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
23360 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
23370 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
23380 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
23390 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
233a0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
233b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
233c0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
233d0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
233e0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
233f0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
23400 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
23410 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
23420 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
23430 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
23440 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
23450 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
23460 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
23470 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
23480 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
23490 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
234a0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
234b0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
234c0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
234d0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
234e0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
234f0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
23500 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
23510 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
23520 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
23530 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
23540 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
23550 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
23560 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
23570 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
23580 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
23590 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
235a0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
235b0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
235c0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
235d0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
235e0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
235f0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
23600 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
23610 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
23620 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
23630 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
23640 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
23650 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
23660 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
23670 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
23680 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
23690 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
236a0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
236b0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
236c0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
236d0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
236e0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
236f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
23700 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
23710 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
23720 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
23730 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
23740 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
23750 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
23760 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
23770 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
23780 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
23790 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
237a0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
237b0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
237c0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
237d0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
237e0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
237f0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
23800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
23810 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
23820 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
23830 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
23840 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
23850 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
23860 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
23870 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
23880 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
23890 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
238a0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
238b0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
238c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
238d0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
238e0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
238f0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
23900 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
23910 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
23920 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23930 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
23940 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
23950 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65  , it was require
23960 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74  d.** after sqlit
23970 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
23980 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  ed anything othe
23990 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
239a0 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  OW] that.** [sql
239b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65  ite3_reset()] be
239c0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61   called before a
239d0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
239e0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
239f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
23a00 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b  Failure to invok
23a10 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
23a20 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20  ()] in this way 
23a30 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20  would.** result 
23a40 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
23a50 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
23a60 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  m sqlite3_step()
23a70 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20  .  But after.** 
23a80 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
23a90 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
23aa0 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b   began calling [
23ab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23ac0 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c   .** automatical
23ad0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
23ae0 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74  mstance rather t
23af0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
23b00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
23b10 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
23b20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
23b30 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
23b40 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
23b50 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
23b60 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
23b70 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
23b80 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
23b90 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
23ba0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
23bb0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
23bc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
23bd0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
23be0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
23bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
23c00 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
23c10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
23c20 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
23c30 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
23c40 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
23c50 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
23c60 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
23c70 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
23c80 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
23c90 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
23ca0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
23cb0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
23cc0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
23cd0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
23ce0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
23cf0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
23d00 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
23d10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23d20 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
23d30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23d40 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
23d50 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
23d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
23d70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
23d80 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
23d90 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
23da0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
23db0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
23dc0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
23dd0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
23de0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
23df0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
23e00 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
23e10 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
23e20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
23e30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
23e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
23e50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
23e60 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
23e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23e80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
23e90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
23ea0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
23eb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
23ec0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
23ed0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
23ee0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
23ef0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
23f00 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
23f10 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
23f20 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
23f30 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
23f40 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
23f50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
23f60 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
23f70 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
23f80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
23f90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
23fa0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
23fb0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
23fc0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
23fd0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
23fe0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
23ff0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24000 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
24010 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
24020 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
24030 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
24040 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
24050 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
24060 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
24070 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
24080 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
24090 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
240a0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
240b0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
240c0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
240d0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
240e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
240f0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
24100 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
24110 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
24120 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
24130 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
24140 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
24150 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
24160 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
24170 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
24180 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
24190 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
241a0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
241b0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
241c0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
241d0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
241e0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
241f0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
24200 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
24210 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
24220 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
24230 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
24240 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
24250 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
24260 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
24270 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
24280 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
24290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
242a0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
242b0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
242c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
242d0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
242e0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
242f0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
24300 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
24310 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
24320 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
24330 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
24340 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
24350 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
24360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24370 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
24380 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
24390 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
243a0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
243b0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
243c0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
243d0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
243e0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
243f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
24400 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
24410 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
24420 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
24430 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
24440 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
24450 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
24460 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
24470 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24480 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
24490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
244a0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
244b0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
244c0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
244d0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
244e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
244f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24500 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
24510 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
24520 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
24530 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
24540 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
24550 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
24560 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
24570 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
24580 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
24590 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
245a0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
245b0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
245c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
245d0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
245e0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
245f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
24600 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
24610 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
24620 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
24630 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
24640 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
24650 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
24660 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
24670 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
24680 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
24690 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
246a0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
246b0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
246c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
246d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
246e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
246f0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
24700 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
24710 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
24720 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
24730 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
24740 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
24750 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
24760 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
24770 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
24780 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
24790 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
247a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
247b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
247c0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
247d0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
247e0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
247f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
24800 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
24810 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
24820 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
24830 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
24840 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
24850 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24860 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
24870 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
24880 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
24890 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
248a0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
248b0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
248c0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
248d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
248e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
248f0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
24900 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
24910 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
24920 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
24930 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
24940 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
24950 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
24960 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
24970 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
24980 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
24990 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
249a0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
249b0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
249c0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
249d0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
249e0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
249f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24a00 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
24a10 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
24a20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
24a30 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
24a40 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
24a50 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
24a60 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
24a70 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
24a80 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
24a90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
24aa0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
24ab0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
24ac0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
24ad0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
24ae0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
24af0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
24b00 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
24b10 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
24b20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
24b30 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
24b40 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
24b50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
24b60 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
24b70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
24b80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
24b90 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
24ba0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
24bb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
24bc0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
24bd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
24be0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
24bf0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
24c00 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
24c10 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
24c20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24c30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
24c40 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
24c50 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
24c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24c70 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
24c80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
24c90 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
24ca0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
24cb0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
24cc0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
24cd0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
24ce0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
24cf0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
24d00 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
24d10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24d20 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
24d30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
24d40 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
24d50 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
24d60 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
24d70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24d80 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
24d90 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
24da0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
24db0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
24dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
24dd0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
24de0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
24df0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24e00 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
24e10 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
24e20 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
24e30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
24e40 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
24e50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
24e60 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
24e70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
24e80 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
24e90 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
24ea0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
24eb0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
24ec0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
24ed0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
24ee0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
24ef0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
24f00 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
24f10 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
24f20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
24f30 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
24f40 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
24f50 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
24f60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
24f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24f80 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
24f90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24fa0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
24fb0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
24fc0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
24fd0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
24fe0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
24ff0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
25000 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
25010 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
25020 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
25030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25040 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
25050 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
25060 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
25070 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
25080 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
25090 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
250a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
250b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
250c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
250d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
250e0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
250f0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
25100 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
25110 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
25120 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
25130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
25140 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
25150 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
25160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
25170 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
25180 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
25190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
251a0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
251b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
251c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
251d0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
251e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
251f0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
25200 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
25210 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
25220 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
25230 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
25240 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
25250 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
25260 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25270 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
25280 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25290 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
252a0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
252b0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
252c0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
252d0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
252e0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
252f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25300 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
25310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
25320 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
25330 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
25340 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
25350 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
25360 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
25370 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
25380 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
25390 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
253a0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
253b0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
253c0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
253d0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
253e0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
253f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
25400 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
25410 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
25420 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
25430 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
25440 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
25450 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
25460 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
25470 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
25480 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
25490 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
254a0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
254b0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
254c0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
254d0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
254e0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
254f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
25500 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
25510 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
25520 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
25530 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
25540 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
25550 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
25560 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
25570 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
25580 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
25590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
255a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
255b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
255c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
255d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
255e0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
255f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
25600 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
25610 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
25620 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
25630 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
25640 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
25650 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
25660 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
25670 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
25680 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
25690 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
256a0 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
256b0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
256c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
256d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
256e0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
256f0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
25700 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
25710 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
25720 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
25730 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
25740 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
25750 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
25760 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
25770 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
25780 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
25790 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
257a0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
257b0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
257c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
257d0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
257e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
257f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
25800 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
25810 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
25820 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
25830 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
25840 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
25850 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
25860 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
25870 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
25880 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
25890 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
258a0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
258b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
258c0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
258d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
258e0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
258f0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
25900 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
25910 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
25920 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
25930 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
25940 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
25950 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
25960 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
25970 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
25980 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
25990 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
259a0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
259b0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
259c0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
259d0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
259e0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
259f0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
25a00 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
25a10 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
25a20 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
25a30 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
25a40 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
25a50 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
25a60 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
25a70 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
25a80 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
25a90 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
25aa0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
25ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
25ac0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
25ad0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
25ae0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
25af0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
25b00 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
25b10 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
25b20 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
25b30 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
25b40 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
25b50 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
25b60 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
25b70 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
25b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25b90 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
25ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25bb0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
25bc0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
25bd0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
25be0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
25bf0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
25c00 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
25c10 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
25c20 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
25c30 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
25c40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
25c50 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
25c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
25c70 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
25c80 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
25c90 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
25ca0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
25cb0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
25cc0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
25cd0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
25ce0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
25cf0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
25d00 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
25d10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
25d20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
25d30 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
25d40 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
25d50 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
25d60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
25d70 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
25d80 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
25d90 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
25da0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
25db0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
25dc0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
25dd0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
25de0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
25df0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
25e00 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
25e10 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
25e20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
25e30 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
25e40 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
25e50 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
25e60 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
25e70 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
25e80 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
25e90 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
25ea0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
25eb0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
25ec0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
25ed0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
25ee0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
25ef0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
25f00 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
25f10 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
25f20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
25f30 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
25f40 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
25f50 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
25f60 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
25f70 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
25f80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25f90 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
25fa0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
25fb0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
25fc0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
25fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
25fe0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
25ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26000 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
26010 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
26020 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
26030 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
26040 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
26050 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
26060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26070 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
26080 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
26090 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
260a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
260b0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
260c0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
260d0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
260e0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
260f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26100 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
26110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26120 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
26130 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
26140 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
26150 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
26160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
26170 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
26180 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
26190 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
261a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
261b0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
261c0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
261d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
261e0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
261f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
26200 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
26210 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
26220 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
26230 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
26240 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
26250 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
26260 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
26270 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
26280 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
26290 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
262a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
262b0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
262c0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
262d0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
262e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
262f0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
26300 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
26310 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
26320 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
26330 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
26340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
26350 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
26360 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
26370 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
26380 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
26390 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
263a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
263b0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
263c0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
263d0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
263e0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
263f0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
26400 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
26410 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
26420 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
26430 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
26440 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
26450 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
26460 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
26470 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
26480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
26490 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
264a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
264b0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
264c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
264d0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
264e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
264f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
26500 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
26510 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
26520 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
26530 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
26540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26550 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
26560 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
26570 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
26580 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
26590 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
265a0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
265b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
265c0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
265d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
265e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
265f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26600 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
26610 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
26620 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
26630 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26640 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
26650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26660 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
26670 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
26680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
26690 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
266a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
266b0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
266c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
266d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
266e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
266f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26700 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
26710 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
26720 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
26730 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26740 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
26750 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
26760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26770 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
26780 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
26790 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
267a0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
267b0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 20  tered no errors 
267c0 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  or.** or if the 
267d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
267e0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
267f0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
26800 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
26810 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
26820 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
26830 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
26840 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
26850 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
26860 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26870 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
26880 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
26890 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
268a0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
268b0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
268c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
268d0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
268e0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
268f0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
26900 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
26910 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
26920 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
26930 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
26940 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
26950 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
26960 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
26970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
26980 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
26990 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
269a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
269b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
269c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
269d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
269e0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
269f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
26a00 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
26a10 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
26a20 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
26a30 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
26a40 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
26a50 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
26a60 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
26a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26a80 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
26a90 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
26aa0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
26ab0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
26ac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26ad0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
26ae0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
26af0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
26b00 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
26b10 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
26b20 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
26b30 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
26b40 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
26b50 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
26b60 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
26b70 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
26b80 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
26b90 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
26ba0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
26bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
26bc0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
26bd0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
26bf0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
26c00 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
26c10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26c20 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
26c30 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
26c40 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
26c50 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
26c60 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
26c70 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
26c80 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
26c90 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
26ca0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
26cb0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
26cc0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
26cd0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
26ce0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
26cf0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
26d00 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
26d10 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
26d20 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
26d30 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
26d40 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
26d50 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
26d60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
26d70 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
26d80 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
26d90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26da0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
26db0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
26dc0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
26dd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
26de0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
26df0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26e00 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
26e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26e20 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
26e30 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
26e40 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
26e50 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
26e60 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
26e70 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
26e80 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
26e90 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
26ea0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
26eb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
26ec0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
26ed0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
26ee0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26ef0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
26f00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26f10 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
26f20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
26f30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
26f40 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
26f50 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
26f60 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
26f70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
26f80 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
26f90 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
26fa0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
26fb0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
26fc0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
26fd0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
26fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
26ff0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
27000 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
27010 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27020 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
27030 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
27040 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
27050 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
27060 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
27070 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
27080 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
27090 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
270a0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
270b0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
270c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
270d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
270e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
270f0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
27100 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
27110 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
27120 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
27130 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
27140 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
27150 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
27160 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
27170 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
27180 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
27190 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
271a0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
271b0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
271c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
271d0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
271e0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
271f0 20 74 68 65 20 74 68 65 20 73 65 63 6f 6e 64 20   the the second 
27200 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
27210 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
27220 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
27230 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
27240 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
27250 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
27260 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
27270 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
27280 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
27290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
272a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
272b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
272c0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
272d0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
272e0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
272f0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
27300 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
27310 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
27320 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
27330 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
27340 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
27350 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
27360 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
27370 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
27380 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
27390 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
273a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
273b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
273c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
273d0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
273e0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
273f0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
27400 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
27410 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
27420 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
27430 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
27440 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
27450 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
27460 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
27470 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
27480 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
27490 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
274a0 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
274b0 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
274c0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
274d0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
274e0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
274f0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
27500 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
27510 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
27520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
27530 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
27540 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
27550 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
27560 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
27570 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
27580 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
27590 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
275a0 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
275b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
275c0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
275d0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
275e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
275f0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
27600 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
27610 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
27620 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
27630 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
27640 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
27650 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
27660 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
27670 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
27680 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
27690 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
276a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
276b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
276c0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
276d0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
276e0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
276f0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
27700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
27710 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
27720 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65  parameters.  Eve
27730 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ry SQL function 
27740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
27750 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77  ust be able to w
27760 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d  ork.** with UTF-
27770 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
27780 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
27790 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
277a0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
277b0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
277c0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
277d0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41  han another.  ^A
277e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
277f0 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  y.** invoke sqli
27800 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27810 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
27820 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27830 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
27840 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
27850 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
27860 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
27870 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
27880 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  Rep..** ^When mu
27890 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
278a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
278b0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
278c0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
278d0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
278e0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
278f0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
27900 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
27910 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
27920 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
27930 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
27940 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
27950 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
27960 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
27970 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
27980 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
27990 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
279a0 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
279b0 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
279c0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
279d0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
279e0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
279f0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
27a00 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
27a10 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
27a20 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
27a30 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
27a40 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
27a50 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
27a60 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
27a70 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
27a80 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
27a90 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
27aa0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
27ab0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
27ac0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
27ad0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
27ae0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
27af0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
27b00 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
27b10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
27b20 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
27b30 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
27b40 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
27b50 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
27b60 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
27b70 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
27b80 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
27b90 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
27ba0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
27bb0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
27bc0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
27bd0 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
27be0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
27bf0 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
27c00 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
27c10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
27c20 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
27c30 55 4c 4c 20 70 6f 69 6e 65 72 73 20 66 6f 72 20  ULL poiners for 
27c40 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
27c50 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
27c60 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
27c70 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
27c80 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
27c90 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
27ca0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
27cb0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
27cc0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
27cd0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
27ce0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
27cf0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
27d00 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
27d10 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
27d20 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
27d30 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
27d40 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
27d50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27d60 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
27d70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
27d80 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
27d90 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
27da0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27db0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
27dc0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
27dd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
27de0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
27df0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
27e00 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
27e10 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
27e20 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
27e30 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
27e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
27e50 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
27e60 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
27e70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
27e80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27e90 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
27ea0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
27eb0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
27ec0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
27ed0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
27ee0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
27ef0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
27f00 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
27f10 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
27f20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
27f30 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
27f40 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
27f50 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
27f60 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
27f70 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
27f80 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
27f90 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
27fa0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
27fb0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
27fc0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
27fd0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
27fe0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
27ff0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
28000 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
28010 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
28020 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
28030 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
28040 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
28050 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
28060 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
28070 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
28080 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
28090 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
280a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
280b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
280c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
280d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
280e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
280f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
28100 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
28110 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
28120 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
28130 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
28140 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
28150 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
28160 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
28170 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
28180 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
28190 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
281a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
281b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
281c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
281d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
281e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
281f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
28200 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28210 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
28220 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
28230 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
28240 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
28250 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
28260 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
28270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
28280 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
28290 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
282a0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
282b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
282c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
282d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
282e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
282f0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
28300 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
28310 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
28320 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
28330 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
28340 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
28350 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
28360 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28370 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
28380 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
28390 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
283a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
283b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
283c0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
283d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
283e0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
283f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28400 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
28410 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
28420 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
28430 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
28440 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
28450 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
28460 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
28470 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
28480 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
28490 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
284a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
284b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
284c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
284d0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
284e0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
284f0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
28500 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
28510 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
28520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
28530 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
28540 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
28550 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
28560 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
28570 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
28580 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
28590 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
285a0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
285b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
285c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
285d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
285e0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
285f0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
28600 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
28610 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28620 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
28630 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
28640 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
28650 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
28660 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
28670 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
28680 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
28690 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
286a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
286b0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
286c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
286d0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
286e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
286f0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
28700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28710 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
28720 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
28730 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
28740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
28750 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
28760 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
28770 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
28780 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
28790 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
287a0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
287b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
287c0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
287d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
287e0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
287f0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
28800 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
28810 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
28820 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
28830 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
28840 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
28850 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
28860 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
28870 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
28880 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
28890 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
288a0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
288b0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
288c0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
288d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
288e0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
288f0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
28900 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
28910 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
28920 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
28930 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
28940 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
28950 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
28960 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
28970 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
28980 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28990 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
289a0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
289b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
289c0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
289d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
289e0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
289f0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
28a00 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
28a10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28a30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
28a40 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
28a50 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
28a60 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
28a70 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
28a80 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
28a90 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
28aa0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
28ab0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
28ac0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
28ad0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
28ae0 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
28af0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
28b00 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
28b10 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
28b20 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
28b30 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
28b40 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
28b50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
28b60 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
28b70 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
28b80 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
28b90 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
28ba0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
28bb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
28bc0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
28bd0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
28be0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
28bf0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
28c00 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
28c10 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
28c20 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
28c30 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
28c40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28c50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28c60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28c70 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
28c80 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
28c90 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
28ca0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
28cb0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
28cc0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
28cd0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
28ce0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
28cf0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
28d00 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
28d10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28d20 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
28d30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28d40 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
28d50 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
28d60 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
28d70 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
28d80 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
28d90 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
28da0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
28db0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28dc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
28dd0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
28de0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
28df0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28e00 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
28e10 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
28e20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
28e30 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
28e40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28e50 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
28e60 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
28e70 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
28e80 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
28e90 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
28ea0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
28eb0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
28ec0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
28ed0 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
28ee0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
28ef0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
28f00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28f10 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
28f20 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
28f30 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
28f40 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
28f50 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
28f60 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
28f70 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
28f80 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
28f90 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
28fa0 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
28fb0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
28fc0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
28fd0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
28fe0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
28ff0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
29000 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
29010 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
29020 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
29030 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
29040 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
29050 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
29060 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
29070 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
29080 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
29090 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
290a0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
290b0 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
290c0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
290d0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
290e0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
290f0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
29100 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
29110 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
29120 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
29130 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
29140 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
29150 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
29160 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
29170 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
29180 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
29190 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
291a0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
291b0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
291c0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
291d0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
291e0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
291f0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
29200 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
29210 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
29220 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
29230 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
29240 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
29250 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
29260 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
29270 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
29280 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
29290 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
292a0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
292b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
292c0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
292d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
292e0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
292f0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
29300 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
29310 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
29320 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
29330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
29340 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
29350 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
29360 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
29370 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
29380 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
29390 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
293a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
293b0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
293c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
293d0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
293e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
293f0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
29400 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
29410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
29420 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
29430 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
29440 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
29450 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
29460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
29470 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
29480 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
29490 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
294a0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
294b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
294c0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
294d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
294e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
294f0 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
29500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
29510 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
29520 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
29530 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
29540 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
29550 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
29560 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
29570 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
29580 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
29590 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
295a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
295b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
295c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
295d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
295e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
295f0 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
29600 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
29610 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
29620 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
29630 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
29640 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
29650 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
29660 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
29670 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
29680 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
29690 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
296a0 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
296b0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
296c0 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
296d0 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
296e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
296f0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
29700 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29710 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
29720 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
29730 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
29740 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
29750 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
29760 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
29770 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
29780 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
29790 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
297a0 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
297b0 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
297c0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
297d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
297e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
297f0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
29800 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
29810 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
29820 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
29830 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
29840 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
29850 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
29860 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
29870 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
29880 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
29890 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
298a0 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
298b0 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
298c0 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
298d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
298e0 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
298f0 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
29900 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
29910 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
29920 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
29930 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
29940 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
29950 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
29960 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
29970 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
29980 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
29990 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
299a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
299b0 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
299c0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
299d0 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
299e0 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
299f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
29a00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29a10 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
29a20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
29a30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
29a40 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
29a50 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
29a60 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
29a70 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  y allocate error
29a80 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
29a90 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
29aa0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
29ab0 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
29ac0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
29ad0 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
29ae0 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
29af0 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
29b00 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
29b10 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
29b20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
29b30 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
29b40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
29b50 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
29b60 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
29b70 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
29b80 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
29b90 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
29ba0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
29bb0 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  tion.)^.**.** ^S
29bc0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
29bd0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
29be0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
29bf0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
29c00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29c10 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
29c20 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
29c30 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
29c40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29c50 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
29c60 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
29c70 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
29c80 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
29c90 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
29ca0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
29cb0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
29cc0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
29cd0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
29ce0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
29cf0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
29d00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
29d10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
29d20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
29d30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
29d40 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
29d50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
29d60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
29d70 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
29d80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29d90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29da0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
29db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29dc0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
29dd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
29de0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
29df0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
29e00 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
29e10 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
29e20 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
29e30 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
29e40 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
29e50 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
29e60 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
29e70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
29e80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
29e90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29ea0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
29eb0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
29ec0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
29ed0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
29ee0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
29ef0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
29f00 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
29f10 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
29f20 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
29f30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29f40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29f50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
29f60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
29f70 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
29f80 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
29f90 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
29fa0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
29fb0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
29fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29fd0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
29fe0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
29ff0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2a000 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2a010 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
2a020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
2a030 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
2a040 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
2a050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a060 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
2a070 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a080 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
2a090 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
2a0a0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
2a0b0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2a0c0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2a0d0 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
2a0e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2a0f0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2a100 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2a110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2a120 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
2a130 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Data.**.** The 
2a140 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
2a150 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
2a160 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
2a170 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
2a180 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
2a190 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
2a1a0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
2a1b0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
2a1c0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
2a1d0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
2a1e0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
2a1f0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
2a200 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
2a210 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
2a220 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
2a230 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
2a240 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
2a250 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
2a260 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
2a270 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
2a280 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
2a290 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
2a2a0 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
2a2b0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
2a2c0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
2a2d0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2a2e0 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
2a2f0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
2a300 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2a310 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
2a320 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
2a330 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
2a340 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
2a350 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
2a360 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
2a370 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
2a380 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
2a390 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2a3a0 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
2a3b0 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
2a3c0 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
2a3d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2a3e0 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
2a3f0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
2a400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a410 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2a420 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a430 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2a440 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2a450 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
2a460 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2a470 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
2a480 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
2a490 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
2a4a0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2a4b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2a4c0 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61  ion. ^If no meta
2a4d0 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
2a4e0 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
2a4f0 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
2a500 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
2a510 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
2a520 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
2a530 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2a540 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
2a550 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
2a560 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
2a570 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
2a580 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
2a590 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a5b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2a5c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
2a5d0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
2a5e0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2a5f0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
2a600 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
2a610 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
2a620 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
2a630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a640 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2a650 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
2a660 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2a670 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
2a680 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
2a690 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
2a6a0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
2a6b0 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69  troyed..** ^If i
2a6c0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
2a6d0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2a6e0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2a6f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
2a700 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
2a710 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2a720 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2a730 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
2a740 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
2a750 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
2a760 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
2a770 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
2a780 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a790 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
2a7a0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
2a7b0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
2a7c0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
2a7d0 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
2a7e0 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
2a7f0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
2a800 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
2a810 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
2a820 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67  me.  ^The only g
2a830 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
2a840 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
2a850 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2a860 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2a870 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
2a880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
2a890 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
2a8a0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
2a8b0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
2a8c0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
2a8d0 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
2a8e0 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
2a8f0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
2a900 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
2a910 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
2a920 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a  arameters].)^.**
2a930 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a940 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2a950 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2a960 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2a970 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2a980 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2a990 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2a9a0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
2a9b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a9c0 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
2a9d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2a9e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a9f0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
2aa00 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
2aa10 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
2aa20 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
2aa30 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
2aa40 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
2aa50 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
2aa60 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
2aa70 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
2aa80 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
2aa90 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
2aaa0 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
2aab0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2aac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2aad0 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
2aae0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2aaf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
2ab00 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
2ab10 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2ab20 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
2ab30 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
2ab40 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
2ab50 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
2ab60 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
2ab70 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
2ab80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ab90 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
2aba0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
2abb0 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
2abc0 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
2abd0 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
2abe0 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
2abf0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
2ac00 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
2ac10 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
2ac20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
2ac30 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
2ac40 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
2ac50 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
2ac60 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
2ac70 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
2ac80 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
2ac90 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
2aca0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
2acb0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
2acc0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
2acd0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
2ace0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2acf0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
2ad00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
2ad10 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
2ad20 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2ad30 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
2ad40 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
2ad50 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
2ad60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
2ad70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ad80 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
2ad90 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
2ada0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
2adb0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
2adc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2add0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
2ade0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
2adf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2ae00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2ae10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ae20 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
2ae30 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2ae40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
2ae50 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
2ae60 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
2ae70 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
2ae80 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
2ae90 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
2aea0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
2aeb0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
2aec0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
2aed0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
2aee0 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
2aef0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
2af00 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2af10 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2af20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2af30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2af40 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
2af50 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2af60 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2af70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2af80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2af90 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
2afa0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
2afb0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
2afc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
2afd0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
2afe0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
2aff0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
2b000 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2b010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2b020 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
2b030 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
2b040 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2b050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2b060 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2b070 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
2b080 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
2b090 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
2b0a0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
2b0b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
2b0c0 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
2b0d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2b0e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2b0f0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
2b100 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2b110 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2b120 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2b130 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b140 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
2b150 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
2b160 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
2b170 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2b180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b190 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2b1a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2b1b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
2b1c0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
2b1d0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
2b1e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2b1f0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
2b200 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
2b210 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
2b220 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2b230 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
2b240 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
2b250 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
2b260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b270 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
2b280 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
2b290 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
2b2a0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
2b2b0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2b2c0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
2b2d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b2e0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
2b2f0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
2b300 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
2b310 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
2b320 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2b330 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
2b340 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
2b350 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
2b360 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b380 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2b390 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b3a0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2b3b0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2b3c0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2b3d0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2b3e0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2b3f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2b400 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
2b410 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2b420 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2b430 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2b440 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
2b450 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2b460 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
2b470 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2b480 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
2b490 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2b4a0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
2b4b0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2b4c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2b4d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b4e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2b4f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2b500 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2b510 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
2b520 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2b530 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2b540 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
2b550 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
2b560 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
2b570 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
2b580 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
2b590 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
2b5a0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
2b5b0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
2b5c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b5d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2b5e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
2b5f0 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
2b600 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
2b610 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
2b620 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
2b630 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
2b640 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
2b650 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
2b660 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
2b670 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
2b680 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b690 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2b6a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b6b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2b6c0 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2b6d0 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2b6e0 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
2b6f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b700 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
2b710 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2b720 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2b730 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
2b740 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
2b750 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
2b760 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
2b770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b780 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
2b790 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2b7a0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
2b7b0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
2b7c0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2b7d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2b7e0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
2b7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2b800 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
2b810 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2b820 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2b830 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2b840 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2b850 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
2b860 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2b870 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2b880 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2b890 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
2b8a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2b8b0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
2b8c0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2b8d0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2b8e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b8f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2b900 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
2b910 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2b920 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2b930 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2b940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b950 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2b960 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2b970 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b980 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2b990 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b9a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
2b9b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2b9c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b9d0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
2b9e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
2b9f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2ba00 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
2ba10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ba20 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
2ba30 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
2ba40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
2ba50 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2ba60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ba70 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
2ba80 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
2ba90 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
2baa0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
2bab0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2bac0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
2bad0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
2bae0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
2baf0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
2bb00 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
2bb10 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
2bb20 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
2bb30 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
2bb40 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2bb50 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
2bb60 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2bb70 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
2bb80 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2bb90 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2bba0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2bbb0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
2bbc0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
2bbd0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
2bbe0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
2bbf0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
2bc00 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2bc10 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2bc20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2bc30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2bc40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bc50 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2bc60 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
2bc70 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
2bc80 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
2bc90 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
2bca0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
2bcb0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
2bcc0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
2bcd0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
2bce0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
2bcf0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
2bd00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2bd10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2bd20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bd30 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2bd40 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2bd50 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2bd60 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2bd70 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2bd80 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2bd90 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2bda0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2bdb0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2bdc0 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2bdd0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2bde0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2bdf0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2be00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2be10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2be20 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
2be30 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
2be40 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2be50 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2be60 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
2be70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
2be80 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2be90 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2bea0 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
2beb0 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
2bec0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
2bed0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2bee0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
2bef0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
2bf00 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
2bf10 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
2bf20 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
2bf30 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
2bf40 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2bf50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2bf60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2bf70 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2bf80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2bf90 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2bfa0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2bfb0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
2bfc0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
2bfd0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2bfe0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
2bff0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
2c000 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
2c010 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
2c020 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
2c030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c040 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c050 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2c060 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
2c070 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2c080 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c090 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
2c0a0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
2c0b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c0c0 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
2c0d0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
2c0e0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
2c0f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2c100 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
2c110 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
2c120 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
2c130 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
2c140 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
2c150 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
2c160 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
2c170 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
2c180 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
2c190 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2c1a0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2c1b0 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
2c1c0 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
2c1d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c1e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
2c1f0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
2c200 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
2c210 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c220 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
2c230 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
2c240 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
2c250 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2c260 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
2c270 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
2c280 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
2c290 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c2a0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2c2b0 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
2c2c0 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
2c2d0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
2c2e0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
2c2f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c300 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
2c310 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
2c320 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2c330 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
2c340 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2c350 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
2c360 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2c370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c380 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2c390 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2c3a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2c3b0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2c3c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c3d0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
2c3e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c3f0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
2c400 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
2c410 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
2c420 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2c430 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
2c440 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2c450 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
2c460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c470 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
2c480 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2c490 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c4a0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
2c4b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2c4c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2c4d0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2c4e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c4f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2c500 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2c510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c520 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2c530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2c540 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
2c550 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
2c560 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
2c570 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
2c580 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2c590 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c5a0 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
2c5b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2c5c0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
2c5d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2c5e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c5f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
2c600 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2c610 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2c620 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2c630 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c640 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
2c650 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2c660 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
2c670 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2c680 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2c690 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
2c6a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2c6b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2c6c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2c6d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c6e0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
2c6f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
2c700 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
2c710 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2c720 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
2c730 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2c740 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
2c750 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
2c760 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
2c770 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
2c780 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
2c790 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
2c7a0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
2c7b0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
2c7c0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2c7d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
2c7e0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
2c7f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
2c800 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
2c810 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
2c820 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2c830 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
2c840 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c850 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
2c860 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2c870 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
2c880 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
2c890 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2c8a0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
2c8b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2c8c0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
2c8d0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
2c8e0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
2c8f0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
2c900 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
2c910 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
2c920 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
2c930 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
2c940 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
2c950 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
2c960 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
2c970 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
2c980 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
2c990 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
2c9a0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2c9b0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
2c9c0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
2c9d0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2c9e0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
2c9f0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2ca00 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
2ca10 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
2ca20 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
2ca30 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
2ca40 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
2ca50 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
2ca60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2ca70 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
2ca80 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
2ca90 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
2caa0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
2cab0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
2cac0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
2cad0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
2cae0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
2caf0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2cb00 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
2cb10 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
2cb20 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
2cb30 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
2cb40 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
2cb50 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
2cb60 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
2cb70 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2cb80 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 20 61  nt, pArg, is a a
2cb90 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2cba0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
2cbb0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
2cbc0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
2cbd0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2cbe0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2cbf0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
2cc00 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2cc10 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
2cc20 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
2cc30 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
2cc40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
2cc50 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
2cc60 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
2cc70 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
2cc80 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
2cc90 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
2cca0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
2ccb0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
2ccc0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
2ccd0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
2cce0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
2ccf0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2cd00 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
2cd10 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
2cd20 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
2cd30 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
2cd40 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
2cd50 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
2cd60 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
2cd70 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
2cd80 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
2cd90 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
2cda0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
2cdb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
2cdc0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
2cdd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
2cde0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
2cdf0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2ce00 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
2ce10 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
2ce20 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2ce30 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
2ce40 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
2ce50 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2ce60 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
2ce70 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
2ce80 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
2ce90 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
2cea0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
2ceb0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
2cec0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
2ced0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
2cee0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
2cef0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
2cf00 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
2cf10 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
2cf20 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
2cf30 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
2cf40 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
2cf50 61 6c 77 61 79 20 72 65 74 75 72 6e 20 74 68 65  alway return the
2cf60 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
2cf70 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
2cf80 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
2cf90 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
2cfa0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
2cfb0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
2cfc0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
2cfd0 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
2cfe0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
2cff0 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
2d000 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
2d010 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
2d020 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
2d030 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
2d040 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
2d050 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2d060 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
2d070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
2d080 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
2d090 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
2d0a0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
2d0b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
2d0c0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
2d0d0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
2d0e0 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
2d0f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
2d100 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
2d110 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
2d120 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
2d130 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
2d140 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
2d150 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d160 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
2d170 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
2d180 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
2d190 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2d1a0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
2d1b0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
2d1c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
2d1d0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
2d1e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d1f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
2d200 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2d210 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
2d220 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d230 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
2d240 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
2d250 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
2d260 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2d270 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
2d280 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
2d290 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
2d2a0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
2d2b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
2d2c0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
2d2d0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2d2e0 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
2d2f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
2d300 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2d310 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
2d320 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
2d330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2d340 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
2d350 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2d360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
2d370 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
2d380 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
2d390 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
2d3a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d3b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
2d3c0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
2d3d0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2d3e0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
2d3f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2d400 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
2d410 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
2d420 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2d430 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
2d440 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
2d450 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
2d460 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2d470 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
2d480 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
2d490 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
2d4a0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
2d4b0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
2d4c0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
2d4d0 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
2d4e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
2d4f0 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
2d500 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
2d510 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
2d520 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
2d530 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
2d540 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
2d550 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
2d560 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2d570 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2d580 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2d590 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2d5a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2d5b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2d5c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2d5d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2d5e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2d5f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2d600 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2d610 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2d620 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2d630 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2d640 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
2d650 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2d660 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
2d670 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2d680 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2d690 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2d6a0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
2d6b0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2d6c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2d6d0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2d6e0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2d6f0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2d700 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2d710 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2d720 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2d730 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
2d740 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
2d750 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
2d760 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
2d770 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2d780 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2d790 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2d7a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d7b0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
2d7c0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
2d7d0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
2d7e0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
2d7f0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
2d800 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
2d810 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
2d820 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
2d830 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
2d840 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
2d850 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
2d860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2d870 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
2d880 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2d890 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
2d8a0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2d8b0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
2d8c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
2d8d0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
2d8e0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
2d8f0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2d900 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
2d910 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
2d920 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
2d930 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
2d940 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2d950 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
2d960 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
2d970 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
2d980 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2d990 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
2d9a0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
2d9b0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
2d9c0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
2d9d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
2d9e0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
2d9f0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
2da00 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
2da10 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
2da20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2da30 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
2da40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2da50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2da60 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2da70 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2da80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2da90 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2daa0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2dab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2dac0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2dad0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2dae0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2daf0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2db00 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
2db10 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2db20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2db30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2db40 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2db50 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
2db60 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
2db70 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2db80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2db90 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
2dba0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
2dbb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2dbc0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2dbd0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
2dbe0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2dbf0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
2dc00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2dc10 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
2dc20 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
2dc30 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
2dc40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2dc50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
2dc60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2dc70 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
2dc80 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2dc90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2dca0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
2dcb0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2dcc0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2dcd0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2dce0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2dcf0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2dd00 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2dd10 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2dd20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2dd30 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2dd40 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2dd50 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2dd60 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2dd70 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2dd80 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
2dd90 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
2dda0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2ddb0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2ddc0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2ddd0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2dde0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2ddf0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2de00 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2de10 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2de20 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2de30 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2de40 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2de50 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2de60 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2de70 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2de80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2de90 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2dea0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2deb0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2dec0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2ded0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2dee0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2def0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2df00 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2df10 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2df20 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2df30 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2df40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2df50 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2df60 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2df70 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2df80 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2df90 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2dfa0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2dfb0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2dfc0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2dfd0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2dfe0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2dff0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2e000 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2e010 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2e020 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2e030 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2e040 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2e050 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2e060 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2e070 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2e080 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2e090 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2e0a0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
2e0b0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2e0c0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2e0d0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
2e0e0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2e0f0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2e100 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
2e110 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2e120 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2e130 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2e140 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
2e150 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
2e160 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
2e170 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2e180 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
2e190 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
2e1a0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2e1b0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2e1c0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
2e1d0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2e1e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2e1f0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2e200 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2e210 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2e220 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2e230 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2e240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2e250 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2e260 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2e270 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2e280 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
2e290 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
2e2a0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2e2b0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2e2c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2e2d0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2e2e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2e2f0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2e300 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
2e310 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2e320 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2e330 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2e340 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2e350 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2e360 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2e370 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2e380 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2e390 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2e3a0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
2e3b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2e3c0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2e3d0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
2e3e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2e3f0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2e400 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
2e410 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2e420 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2e430 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2e440 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2e450 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2e460 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2e470 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
2e480 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
2e490 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
2e4a0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
2e4b0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
2e4c0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
2e4d0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
2e4e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2e4f0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
2e500 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
2e510 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
2e520 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
2e530 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
2e540 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
2e550 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2e560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e570 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2e580 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2e590 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
2e5a0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
2e5b0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2e5c0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2e5d0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2e5e0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2e5f0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
2e600 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2e610 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2e620 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2e630 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
2e640 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
2e650 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
2e660 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
2e670 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
2e680 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
2e690 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2e6a0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
2e6b0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2e6c0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
2e6d0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
2e6e0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
2e6f0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
2e700 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
2e710 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2e720 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2e730 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
2e740 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
2e750 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
2e760 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
2e770 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
2e780 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
2e790 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
2e7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2e7b0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
2e7c0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
2e7d0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
2e7e0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
2e7f0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2e800 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2e810 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2e820 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2e830 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2e840 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2e850 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2e860 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2e870 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
2e880 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2e890 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2e8a0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
2e8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
2e8c0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2e8d0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
2e8e0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2e8f0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
2e900 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
2e910 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2e920 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2e930 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
2e940 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
2e950 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2e960 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
2e970 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
2e980 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
2e990 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
2e9a0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
2e9b0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
2e9c0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
2e9d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
2e9e0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
2e9f0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
2ea00 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
2ea10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
2ea20 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
2ea30 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
2ea40 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
2ea50 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
2ea60 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
2ea70 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
2ea80 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2ea90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2eaa0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2eab0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
2eac0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
2ead0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2eae0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
2eaf0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
2eb00 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
2eb10 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
2eb20 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
2eb30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
2eb40 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
2eb50 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
2eb60 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
2eb70 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
2eb80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2eb90 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
2eba0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2ebb0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2ebc0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2ebd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ebe0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2ebf0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2ec00 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2ec10 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
2ec20 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
2ec30 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
2ec40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
2ec50 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
2ec60 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
2ec70 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2ec80 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
2ec90 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
2eca0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
2ecb0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
2ecc0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
2ecd0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
2ece0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
2ecf0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
2ed00 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
2ed10 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
2ed20 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
2ed30 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
2ed40 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
2ed50 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
2ed60 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
2ed70 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
2ed80 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
2ed90 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
2eda0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
2edb0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
2edc0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
2edd0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
2ede0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2edf0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
2ee00 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
2ee10 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
2ee20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
2ee30 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
2ee40 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
2ee50 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
2ee60 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
2ee70 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2ee80 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
2ee90 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
2eea0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
2eeb0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
2eec0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
2eed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
2eee0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
2eef0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
2ef00 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
2ef10 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
2ef20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
2ef30 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
2ef40 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
2ef50 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
2ef60 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
2ef70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ef80 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
2ef90 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
2efa0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
2efb0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
2efc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2efd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2efe0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2eff0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
2f000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f010 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
2f020 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f030 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
2f040 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2f050 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
2f060 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
2f070 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
2f080 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
2f090 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
2f0a0 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
2f0b0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
2f0c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
2f0d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2f0e0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
2f0f0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
2f100 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
2f110 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2f120 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2f130 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
2f140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f150 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
2f160 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2f170 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f180 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
2f190 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
2f1a0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
2f1b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f1c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2f1d0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
2f1e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
2f1f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2f200 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f210 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
2f220 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
2f230 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
2f240 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
2f250 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
2f260 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
2f270 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
2f280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f290 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
2f2a0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2f2b0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2f2c0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
2f2d0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
2f2e0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2f2f0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
2f300 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
2f310 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2f320 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
2f330 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
2f340 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
2f350 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
2f360 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f370 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
2f380 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
2f390 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2f3a0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2f3b0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2f3c0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2f3d0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2f3e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
2f3f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2f400 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
2f410 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
2f420 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
2f430 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
2f440 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2f450 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2f460 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2f470 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2f480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f490 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2f4a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2f4b0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2f4c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2f4d0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2f4e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2f4f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2f500 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2f510 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
2f520 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
2f530 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2f540 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2f550 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2f560 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2f570 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2f580 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f590 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2f5a0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
2f5b0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2f5c0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
2f5d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2f5e0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
2f5f0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
2f600 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
2f610 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
2f620 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
2f630 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2f640 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
2f650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f660 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
2f670 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
2f680 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
2f690 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
2f6a0 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
2f6b0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2f6c0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2f6d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2f6e0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
2f6f0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2f700 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
2f710 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
2f720 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
2f730 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
2f740 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  D..**.** The cal
2f750 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
2f760 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
2f770 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
2f780 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
2f790 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f7a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
2f7b0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
2f7c0 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
2f7d0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
2f7e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f7f0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
2f800 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
2f810 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
2f820 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
2f830 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
2f840 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
2f850 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
2f860 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
2f870 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2f880 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2f890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2f8a0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2f8b0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2f8c0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2f8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f8e0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2f8f0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2f900 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2f910 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
2f920 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
2f930 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
2f940 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2f950 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
2f960 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
2f970 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
2f980 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
2f990 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
2f9a0 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
2f9b0 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
2f9c0 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
2f9d0 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
2f9e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
2f9f0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
2fa00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2fa10 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
2fa20 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2fa30 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
2fa40 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
2fa50 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
2fa60 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
2fa70 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
2fa80 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
2fa90 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
2faa0 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
2fab0 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
2fac0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
2fad0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
2fae0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
2faf0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
2fb00 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
2fb10 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
2fb20 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
2fb30 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
2fb40 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
2fb50 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
2fb60 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
2fb70 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
2fb80 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
2fb90 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2fba0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2fbb0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
2fbc0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2fbd0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
2fbe0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2fbf0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
2fc00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2fc10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
2fc20 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
2fc30 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
2fc40 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
2fc50 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
2fc60 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
2fc70 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
2fc80 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2fc90 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
2fca0 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
2fcb0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
2fcc0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
2fcd0 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
2fce0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2fcf0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
2fd00 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
2fd10 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2fd20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2fd30 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
2fd40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd50 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
2fd60 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
2fd70 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
2fd80 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2fd90 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2fda0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2fdb0 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
2fdc0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2fdd0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2fde0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2fdf0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2fe00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fe10 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2fe20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2fe30 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2fe40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2fe50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
2fe60 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
2fe70 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2fe80 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2fe90 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
2fea0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2feb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
2fec0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
2fed0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2fee0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2fef0 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
2ff00 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
2ff10 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2ff20 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
2ff30 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
2ff40 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
2ff50 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
2ff60 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
2ff70 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
2ff80 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
2ff90 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
2ffa0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2ffb0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
2ffc0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
2ffd0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
2ffe0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
2fff0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
30000 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
30010 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
30020 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
30030 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
30040 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
30050 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
30060 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
30070 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
30080 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
30090 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
300a0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
300b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
300c0 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
300d0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
300e0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
300f0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
30100 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
30110 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
30120 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
30130 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
30140 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
30150 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
30160 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
30170 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
30180 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
30190 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
301a0 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
301b0 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
301c0 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
301d0 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
301e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
301f0 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
30200 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
30210 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
30220 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
30230 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
30240 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
30250 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
30260 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
30270 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
30280 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
30290 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
302a0 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
302b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
302c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
302d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
302e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
302f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
30300 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
30310 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
30320 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
30330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30340 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
30350 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
30360 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
30370 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
30380 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
30390 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
303a0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
303b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
303c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
303d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
303e0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
303f0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
30400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30410 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
30420 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
30430 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
30440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30450 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
30460 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
30470 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
30480 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
30490 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
304a0 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
304b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
304c0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
304d0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
304e0 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
304f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
30500 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
30510 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71  _hook()] and [sq
30520 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
30530 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ook()].** interf
30540 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  aces..*/.void *s
30550 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
30560 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
30570 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
30580 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
30590 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
305a0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
305b0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
305c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
305d0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
305e0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
305f0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
30600 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a  shared cache}.**
30610 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
30620 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
30630 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
30640 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
30650 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
30660 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
30670 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
30680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30690 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
306a0 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
306b0 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
306c0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
306d0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
306e0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
306f0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
30700 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
30710 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20  )^.**.** ^Cache 
30720 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
30730 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
30740 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
30750 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69  ocess..** This i
30760 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
30770 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
30780 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
30790 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
307a0 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
307b0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
307c0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
307d0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
307e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63  y..**.** ^(The c
307f0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
30800 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
30810 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
30820 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
30830 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
30840 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
30850 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
30860 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
30870 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
30880 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
30890 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
308a0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
308b0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
308c0 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
308d0 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
308e0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a  were opened.)^.*
308f0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
30900 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
30910 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
30920 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
30930 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
30940 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
30950 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
30960 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
30970 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  herwise.)^.**.**
30980 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69   ^Shared cache i
30990 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
309a0 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
309b0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
309c0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
309d0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
309e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
309f0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
30a00 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
30a10 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
30a20 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
30a30 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b  .** See Also:  [
30a40 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61  SQLite Shared-Ca
30a50 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74  che Mode].*/.int
30a60 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
30a70 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
30a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30a90 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46  EF: Attempt To F
30aa0 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
30ab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30ac0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
30ad0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
30ae0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e  tempts to free N
30af0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61   bytes.** of hea
30b00 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
30b10 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
30b20 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ential memory al
30b30 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c  locations.** hel
30b40 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
30b50 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d  e library.   Mem
30b60 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
30b70 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
30b80 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
30b90 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
30ba0 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
30bb0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
30bc0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
30bd0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
30be0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
30bf0 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
30c00 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68  lly freed,.** wh
30c10 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
30c20 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74  e or less than t
30c30 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
30c40 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
30c50 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30c60 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ory() routine is
30c70 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69   a no-op returni
30c80 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51  ng zero.** if SQ
30c90 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70  Lite is not comp
30ca0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
30cb0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
30cc0 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a  MANAGEMENT]..*/.
30cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
30ce0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
30cf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30d00 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
30d10 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
30d20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30d30 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
30d40 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
30d50 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69  ets and/or queri
30d60 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c  es the.** soft l
30d70 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
30d80 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
30d90 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
30da0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
30db0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74  e..** ^SQLite st
30dc0 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65  rives to keep he
30dd0 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a  ap memory utiliz
30de0 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20  ation below the 
30df0 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d  soft heap.** lim
30e00 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74  it by reducing t
30e10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
30e20 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  es held in the p
30e30 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20  age cache.** as 
30e40 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67  heap memory usag
30e50 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68  es approaches th
30e60 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
30e70 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
30e80 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75   is "soft" becau
30e90 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53  se even though S
30ea0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
30eb0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74   stay.** below t
30ec0 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c  he limit, it wil
30ed0 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d  l exceed the lim
30ee0 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67  it rather than g
30ef0 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53  enerate.** an [S
30f00 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72  QLITE_NOMEM] err
30f10 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  or.  In other wo
30f20 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65  rds, the soft he
30f30 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20  ap limit .** is 
30f40 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
30f50 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
30f60 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
30f70 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
30f80 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73  mit64() is the s
30f90 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f  ize of.** the so
30fa0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72  ft heap limit pr
30fb0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
30fc0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65    ^If the argume
30fd0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  nt N is negative
30fe0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  .** then no chan
30ff0 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68  ge is made to th
31000 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31010 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  t.  Hence, the c
31020 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f  urrent.** size o
31030 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
31040 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74  limit can be det
31050 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b  ermined by invok
31060 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
31070 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
31080 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69  () with a negati
31090 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ve argument..**.
310a0 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
310b0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68  ent N is zero th
310c0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  en the soft heap
310d0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c   limit is disabl
310e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
310f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
31100 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20  is not enforced 
31110 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  in the current i
31120 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
31130 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   if one or more 
31140 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  of following con
31150 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65  ditions are true
31160 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
31170 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65  <li> The soft he
31180 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  ap limit is set 
31190 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e  to zero..** <li>
311a0 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   Memory accounti
311b0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75  ng is disabled u
311c0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69  sing a combinati
311d0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  on of the.**    
311e0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
311f0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
31200 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e  G_MEMSTATUS],...
31210 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74  ) start-time opt
31220 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
31230 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  the [SQLITE_DEFA
31240 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  ULT_MEMSTATUS] c
31250 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
31260 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61  on..** <li> An a
31270 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20  lternative page 
31280 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
31290 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 65 64  tion is specifed
312a0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
312b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
312c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
312d0 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20  CACHE],...)..** 
312e0 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61  <li> The page ca
312f0 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72  che allocates fr
31300 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72  om its own memor
31310 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a  y pool supplied.
31320 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69  **      by [sqli
31330 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
31340 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
31350 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65  ACHE],...) rathe
31360 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66  r than.**      f
31370 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a  rom the heap..**
31380 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42   </ul>)^.**.** B
31390 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
313a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
313b0 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .3, the soft hea
313c0 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72  p limit is enfor
313d0 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ced.** regardles
313e0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
313f0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
31400 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
31410 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d  NAGEMENT].** com
31420 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
31430 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69   is invoked.  Wi
31440 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  th [SQLITE_ENABL
31450 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
31460 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66  ENT],.** the sof
31470 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
31480 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72  enforced on ever
31490 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
314a0 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a  ion.  Without.**
314b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
314c0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
314d0 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  T], the soft hea
314e0 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20  p limit is only 
314f0 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e  enforced.** when
31500 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
31510 61 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65  ated by the page
31520 20 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67   cache.  Testing
31530 20 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62   suggests that b
31540 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61  ecause.** the pa
31550 67 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20  ge cache is the 
31560 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f  predominate memo
31570 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74  ry user in SQLit
31580 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  e, most.** appli
31590 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68  cations will ach
315a0 69 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f  ieve adequate so
315b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e  ft heap limit en
315c0 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75  forcement withou
315d0 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  t.** the use of 
315e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
315f0 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
31600 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72  ]..**.** The cir
31610 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72  cumstances under
31620 20 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69   which SQLite wi
31630 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73  ll enforce the s
31640 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d  oft heap limit m
31650 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  ay.** changes in
31660 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
31670 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73   of SQLite..*/.s
31680 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31690 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
316a0 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69  imit64(sqlite3_i
316b0 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt64 N);../*.** 
316c0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
316d0 61 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c  ated Soft Heap L
316e0 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a  imit Interface.*
316f0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
31700 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70  ** This is a dep
31710 72 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20  recated version 
31720 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
31730 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
31740 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  4()].** interfac
31750 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
31760 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
31770 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
31780 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c  atibility.** onl
31790 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c  y.  All new appl
317a0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
317b0 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  use the.** [sqli
317c0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
317d0 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61  mit64()] interfa
317e0 63 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74  ce rather than t
317f0 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49  his one..*/.SQLI
31800 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
31810 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
31820 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e  heap_limit(int N
31830 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
31840 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74  REF: Extract Met
31850 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f  adata About A Co
31860 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a  lumn Of A Table.
31870 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
31880 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61  ine returns meta
31890 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
318a0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
318b0 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61  a specific.** da
318c0 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63  tabase table acc
318d0 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
318e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
318f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
31900 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
31910 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61  first function a
31920 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
31930 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
31940 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
31950 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
31960 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
31970 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66  ers to.** this f
31980 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65  unction. ^The se
31990 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
319a0 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
319b0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
319c0 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
319d0 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e  ", "temp", or an
319e0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
319f0 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
31a00 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
31a10 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e  table or NULL. ^
31a20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
31a30 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
31a40 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
31a50 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
31a60 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
31a70 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
31a80 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61  m used by the da
31a90 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f  tabase engine to
31aa0 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
31ab0 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
31ac0 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
31ad0 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
31ae0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
31af0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
31b00 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
31b10 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61  and column.** na
31b20 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65  me of the desire
31b30 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63  d column, respec
31b40 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20  tively. Neither 
31b50 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
31b60 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  ers.** may be NU
31b70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64  LL..**.** ^Metad
31b80 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20  ata is returned 
31b90 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  by writing to th
31ba0 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f  e memory locatio
31bb0 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ns passed as the
31bc0 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73   5th.** and subs
31bd0 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
31be0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
31bf0 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73  on. ^Any of thes
31c00 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  e arguments may 
31c10 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77  be.** NULL, in w
31c20 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
31c30 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
31c40 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20  ent of metadata 
31c50 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  is omitted..**.*
31c60 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  * ^(<blockquote>
31c70 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
31c80 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
31c90 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68  h> Parameter <th
31ca0 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65  > Output<br>Type
31cb0 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69   <th>  Descripti
31cc0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
31cd0 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74  > 5th <td> const
31ce0 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61   char* <td> Data
31cf0 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64   type.** <tr><td
31d00 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74  > 6th <td> const
31d10 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65   char* <td> Name
31d20 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c   of default coll
31d30 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a  ation sequence.*
31d40 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c  * <tr><td> 7th <
31d50 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
31d60 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
31d70 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
31d80 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
31d90 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74   <tr><td> 8th <t
31da0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
31db0 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
31dc0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
31dd0 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
31de0 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74   <tr><td> 9th <t
31df0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
31e00 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
31e10 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45  mn is [AUTOINCRE
31e20 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65  MENT].** </table
31e30 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
31e40 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
31e50 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
31e60 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
31e70 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
31e80 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  rned for the.** 
31e90 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65  declaration type
31ea0 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   and collation s
31eb0 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64  equence is valid
31ec0 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20   only until the 
31ed0 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  next.** call to 
31ee0 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66  any SQLite API f
31ef0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
31f00 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
31f10 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
31f20 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65  ly a view, an [e
31f30 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
31f40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  turned..**.** ^I
31f50 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
31f60 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
31f70 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
31f80 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
31f90 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
31fa0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
31fb0 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
31fc0 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
31fd0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
31fe0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
31ff0 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
32000 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
32010 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20  umn. ^(If there 
32020 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
32030 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e  tly declared [IN
32040 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
32050 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20  Y] column, then 
32060 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
32070 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
32080 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
32090 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
320a0 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
320b0 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
320c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
320d0 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
320e0 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
320f0 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
32100 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
32110 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
32120 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  pre>)^.**.** ^(T
32130 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
32140 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
32150 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
32160 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
32170 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
32180 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
32190 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
321a0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
321b0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
321c0 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
321d0 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
321e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
321f0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
32200 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68  ge left.** in th
32210 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
32220 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72  ection] (to be r
32230 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
32240 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
32250 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  .)^.**.** ^This 
32260 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
32270 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
32280 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
32290 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
322a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
322b0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
322c0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
322d0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  bol defined..*/.
322e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c  int sqlite3_tabl
322f0 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74  e_column_metadat
32300 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  a(.  sqlite3 *db
32310 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
32320 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68   /* Connection h
32330 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
32340 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
32350 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
32360 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20  se name or NULL 
32370 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
32380 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20  *zTableName,    
32390 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a   /* Table name *
323a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
323b0 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20  zColumnName,    
323c0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a  /* Column name *
323d0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
323e0 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20  *pzDataType,    
323f0 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61  /* OUTPUT: Decla
32400 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f  red data type */
32410 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
32420 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f  pzCollSeq,     /
32430 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74  * OUTPUT: Collat
32440 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ion sequence nam
32450 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74  e */.  int *pNot
32460 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20  Null,           
32470 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
32480 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63  ue if NOT NULL c
32490 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73  onstraint exists
324a0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d   */.  int *pPrim
324b0 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20  aryKey,         
324c0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
324d0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74  e if column part
324e0 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20   of PK */.  int 
324f0 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20  *pAutoinc       
32500 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
32510 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
32520 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d  n is auto-increm
32530 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ent */.);../*.**
32540 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20   CAPI3REF: Load 
32550 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a  An Extension.**.
32560 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
32570 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69  ce loads an SQLi
32580 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
32590 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61  rary from the na
325a0 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  med file..**.** 
325b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61  ^The sqlite3_loa
325c0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
325d0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
325e0 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53   to load an.** S
325f0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
32600 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65  library containe
32610 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46  d in the file zF
32620 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ile..**.** ^The 
32630 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
32640 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20  Proc..** ^zProc 
32650 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69  may be 0, in whi
32660 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65  ch case the name
32670 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f   of the entry po
32680 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20  int.** defaults 
32690 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65  to "sqlite3_exte
326a0 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20  nsion_init"..** 
326b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61  ^The sqlite3_loa
326c0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
326d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
326e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ** [SQLITE_OK] o
326f0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
32700 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
32710 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
32720 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20  rong..** ^If an 
32730 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64  error occurs and
32740 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74   pzErrMsg is not
32750 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20   0, then the.** 
32760 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
32770 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
32780 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d  face shall attem
32790 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70  pt to.** fill *p
327a0 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72  zErrMsg with err
327b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
327c0 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79  stored in memory
327d0 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
327e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
327f0 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e  c()]. The callin
32800 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68  g function.** sh
32810 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
32820 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67  emory by calling
32830 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
32840 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73  ]..**.** ^Extens
32850 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
32860 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
32870 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e  g.** [sqlite3_en
32880 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
32890 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20  ion()] prior to 
328a0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49  calling this API
328b0 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ,.** otherwise a
328c0 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
328d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
328e0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f  See also the [lo
328f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53  ad_extension() S
32900 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f  QL function]..*/
32910 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
32920 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
32930 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32940 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
32950 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
32960 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
32970 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
32980 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
32990 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
329a0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
329b0 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
329c0 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
329d0 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
329e0 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
329f0 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
32a00 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
32a10 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
32a20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
32a30 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
32a40 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
32a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32a60 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
32a70 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
32a80 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73  ing.**.** ^So as
32a90 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
32aa0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
32ab0 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
32ac0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
32ad0 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
32ae0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
32af0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
32b00 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
32b10 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
32b20 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
32b30 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
32b40 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
32b50 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
32b60 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  * is provided to
32b70 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
32b80 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
32b90 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
32ba0 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a  n and off..**.**
32bb0 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
32bc0 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65  ing is off by de
32bd0 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65  fault. See ticke
32be0 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c  t #1863..** ^Cal
32bf0 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
32c00 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
32c10 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69  ion() routine wi
32c20 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74  th onoff==1.** t
32c30 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
32c40 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20   loading on and 
32c50 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f  call it with ono
32c60 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a  ff==0 to turn.**
32c70 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
32c80 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  in..*/.int sqlit
32c90 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
32ca0 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
32cb0 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
32cc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32cd0 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  F: Automatically
32ce0 20 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79   Load Statically
32cf0 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f   Linked Extensio
32d00 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  ns.**.** ^This i
32d10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
32d20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  the xEntryPoint(
32d30 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  ) function to be
32d40 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20   invoked for.** 
32d50 65 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  each new [databa
32d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
32d70 68 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20  hat is created. 
32d80 20 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69   The idea here i
32d90 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79  s that.** xEntry
32da0 50 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65  Point() is the e
32db0 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61  ntry point for a
32dc0 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b   statically link
32dd0 65 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ed SQLite extens
32de0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74  ion.** that is t
32df0 6f 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  o be automatical
32e00 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61  ly loaded into a
32e10 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ll new database 
32e20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  connections..**.
32e30 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68  ** ^(Even though
32e40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72   the function pr
32e50 6f 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68  ototype shows th
32e60 61 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  at xEntryPoint()
32e70 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67   takes.** no arg
32e80 75 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72  uments and retur
32e90 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20  ns void, SQLite 
32ea0 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f  invokes xEntryPo
32eb0 69 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65  int() with three
32ec0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e  .** arguments an
32ed0 64 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e  d expects and in
32ee0 74 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20  teger result as 
32ef0 69 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65  if the signature
32f00 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79   of the.** entry
32f10 20 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20   point where as 
32f20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
32f30 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
32f40 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20  .** &nbsp;  int 
32f50 78 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20  xEntryPoint(.** 
32f60 26 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65  &nbsp;    sqlite
32f70 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b  3 *db,.** &nbsp;
32f80 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a      const char *
32f90 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e  *pzErrMsg,.** &n
32fa0 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74  bsp;    const st
32fb0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69  ruct sqlite3_api
32fc0 5f 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e  _routines *pThun
32fd0 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a  k.** &nbsp;  );.
32fe0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
32ff0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49  quote>)^.**.** I
33000 66 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  f the xEntryPoin
33010 74 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e  t routine encoun
33020 74 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69  ters an error, i
33030 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70  t should make *p
33040 7a 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74  zErrMsg.** point
33050 20 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61   to an appropria
33060 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
33070 20 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20   (obtained from 
33080 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
33090 28 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75  ()]).** and retu
330a0 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  rn an appropriat
330b0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20  e [error code]. 
330c0 20 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73   ^SQLite ensures
330d0 20 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a   that *pzErrMsg.
330e0 2a 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72  ** is NULL befor
330f0 65 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45  e calling the xE
33100 6e 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53  ntryPoint().  ^S
33110 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
33120 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  e.** [sqlite3_fr
33130 65 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d  ee()] on *pzErrM
33140 73 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50  sg after xEntryP
33150 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20  oint() returns. 
33160 20 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74   ^If any.** xEnt
33170 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e  ryPoint() return
33180 73 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20  s an error, the 
33190 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
331a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
331b0 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  6()],.** or [sql
331c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
331d0 63 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b  call that provok
331e0 65 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69  ed the xEntryPoi
331f0 6e 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a  nt() will fail..
33200 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
33210 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
33220 6e 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e  nsion(X) with an
33230 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74   entry point X t
33240 68 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a  hat is already.*
33250 2a 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66  * on the list of
33260 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
33270 73 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c  sions is a harml
33280 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65  ess no-op. ^No e
33290 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69  ntry point.** wi
332a0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72  ll be called mor
332b0 65 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20  e than once for 
332c0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
332d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73  nnection that is
332e0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   opened..**.** S
332f0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
33300 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
33310 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e  ension()]..*/.in
33320 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
33330 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a  xtension(void (*
33340 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69  xEntryPoint)(voi
33350 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d));../*.** CAPI
33360 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f  3REF: Reset Auto
33370 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20  matic Extension 
33380 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54  Loading.**.** ^T
33390 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69  his interface di
333a0 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d  sables all autom
333b0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
333c0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65  previously.** re
333d0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
333e0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
333f0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f  ension()]..*/.vo
33400 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  id sqlite3_reset
33410 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
33420 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  void);../*.** Th
33430 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
33440 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
33450 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
33460 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
33470 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
33480 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
33490 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
334a0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
334b0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
334c0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
334d0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
334e0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
334f0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
33500 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
33510 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
33520 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
33530 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
33540 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
33550 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
33560 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
33570 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
33580 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
33590 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63  .*/../*.** Struc
335a0 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68  tures used by th
335b0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
335c0 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70  interface.*/.typ
335d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
335e0 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33  te3_vtab sqlite3
335f0 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73  _vtab;.typedef s
33600 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
33610 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33  dex_info sqlite3
33620 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70  _index_info;.typ
33630 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
33640 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
33650 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
33660 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72  sor;.typedef str
33670 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
33680 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  le sqlite3_modul
33690 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
336a0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
336b0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
336c0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f  ORDS: sqlite3_mo
336d0 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61  dule {virtual ta
336e0 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a  ble module}.**.*
336f0 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65  * This structure
33700 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c  , sometimes call
33710 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20  ed a a "virtual 
33720 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a  table module", .
33730 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ** defines the i
33740 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
33750 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
33760 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73  es].  .** This s
33770 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
33780 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  s mostly of meth
33790 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
337a0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72  le..**.** ^A vir
337b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
337c0 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20  e is created by 
337d0 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72  filling in a per
337e0 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61  sistent.** insta
337f0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
33800 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e  cture and passin
33810 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  g a pointer to t
33820 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  hat instance.** 
33830 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
33840 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20  te_module()] or 
33850 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33860 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a  module_v2()]..**
33870 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69   ^The registrati
33880 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  on remains valid
33890 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70   until it is rep
338a0 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65  laced by a diffe
338b0 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f  rent.** module o
338c0 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74  r until the [dat
338d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
338e0 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63  ] closes.  The c
338f0 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69  ontent.** of thi
33900 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  s structure must
33910 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c   not change whil
33920 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72  e it is register
33930 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64  ed with.** any d
33940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33950 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  on..*/.struct sq
33960 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
33970 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
33980 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
33990 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
339a0 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
339b0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
339c0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
339d0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
339e0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
339f0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
33a00 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
33a10 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
33a20 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
33a30 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
33a40 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
33a50 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
33a60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
33a70 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
33a80 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
33a90 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
33aa0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
33ab0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
33ac0 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
33ad0 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
33ae0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
33af0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
33b00 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
33b10 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
33b20 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
33b30 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
33b40 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
33b50 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
33b60 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
33b70 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
33b80 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
33b90 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
33ba0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
33bb0 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
33bc0 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
33bd0 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
33be0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
33bf0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
33c00 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
33c10 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
33c20 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
33c30 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
33c40 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
33c50 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
33c60 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
33c70 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
33c80 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
33c90 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
33ca0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
33cb0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
33cc0 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
33cd0 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
33ce0 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
33cf0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
33d00 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
33d10 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
33d20 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
33d30 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
33d40 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
33d50 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
33d60 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
33d70 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
33d80 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
33d90 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
33da0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
33db0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
33dc0 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
33dd0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
33de0 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
33df0 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
33e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33e10 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
33e20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33e30 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
33e40 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
33e50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
33e60 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
33e70 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
33e80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
33e90 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
33ea0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
33eb0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
33ec0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
33ed0 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  g Information.**
33ee0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
33ef0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a  e3_index_info.**
33f00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33f10 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
33f20 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
33f30 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
33f40 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66  ed as part.** of
33f50 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
33f60 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20 74  ble] interface t
33f70 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
33f80 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
33f90 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
33fa0 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74   from the [xBest
33fb0 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64  Index].** method
33fc0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
33fd0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54  able module].  T
33fe0 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20  he fields under 
33ff0 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74  **Inputs** are t
34000 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20  he.** inputs to 
34010 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61  xBestIndex and a
34020 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78  re read-only.  x
34030 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74  BestIndex insert
34040 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73  s its.** results
34050 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70   into the **Outp
34060 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a  uts** fields..**
34070 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74  .** ^(The aConst
34080 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
34090 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
340a0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
340b0 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a  f the form:.**.*
340c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f  * <blockquote>co
340d0 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c  lumn OP expr</bl
340e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
340f0 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
34100 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
34110 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e  , or &gt;=.)^  ^
34120 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20  (The particular 
34130 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73  operator is.** s
34140 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72  tored in aConstr
34150 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20  aint[].op using 
34160 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53  one of the.** [S
34170 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
34180 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49  TRAINT_EQ | SQLI
34190 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
341a0 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a  INT_ values].)^.
341b0 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f  ** ^(The index o
341c0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
341d0 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f  stored in.** aCo
341e0 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
341f0 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72  mn.)^  ^(aConstr
34200 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
34210 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
34220 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
34230 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
34240 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
34250 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
34260 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
34270 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
34280 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a   it cannot.)^.**
34290 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a  .** ^The optimiz
342a0 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
342b0 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
342c0 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
342d0 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
342e0 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
342f0 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
34300 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
34310 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
34320 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
34330 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
34340 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
34350 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
34360 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
34370 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^The aConstraint
34380 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
34390 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
343a0 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72  se terms that ar
343b0 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f  e.** relevant to
343c0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
343d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
343e0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
343f0 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  ** ^Information 
34400 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
34410 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
34420 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
34430 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d  ]..** ^Each term
34440 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
34450 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
34460 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
34470 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
34480 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
34490 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
344a0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
344b0 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
344c0 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
344d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
344e0 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
344f0 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20  ^If argvIndex>0 
34500 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68  then.** the righ
34510 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
34520 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
34530 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69   aConstraint[] i
34540 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61  s evaluated.** a
34550 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61  nd becomes the a
34560 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72  rgvIndex-th entr
34570 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66  y in argv.  ^(If
34580 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
34590 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
345a0 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
345b0 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
345c0 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
345d0 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
345e0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
345f0 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
34600 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
34610 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te.)^.**.** ^The
34620 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
34630 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
34640 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
34650 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
34660 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
34670 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65  ** ^[sqlite3_fre
34680 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
34690 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
346a0 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65  nd only if.** ne
346b0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
346c0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s true..**.** ^T
346d0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
346e0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
346f0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
34700 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
34710 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
34720 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
34730 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
34740 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
34750 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
34760 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
34770 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
34780 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61  *.** ^The estima
34790 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
347a0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
347b0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
347c0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
347d0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
347e0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
347f0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
34800 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
34810 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
34820 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
34830 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
34840 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
34850 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
34860 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
34870 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
34880 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
34890 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
348a0 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
348b0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
348c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
348d0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
348e0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
348f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
34900 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
34910 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
34920 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
34930 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
34940 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
34950 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
34960 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
34970 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
34980 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
34990 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
349a0 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
349b0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
349c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
349d0 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
349e0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
349f0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
34a00 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
34a10 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
34a20 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
34a30 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
34a40 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
34a50 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
34a60 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
34a70 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
34a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
34a90 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
34aa0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
34ab0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
34ac0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
34ad0 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
34ae0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
34af0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
34b00 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
34b10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
34b20 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
34b30 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
34b40 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
34b50 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
34b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
34b70 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
34b80 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
34b90 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
34ba0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
34bb0 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
34bc0 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
34bd0 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
34be0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
34bf0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
34c00 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
34c10 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
34c20 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
34c30 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
34c40 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
34c50 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
34c60 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
34c70 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
34c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34c90 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
34ca0 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
34cb0 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
34cc0 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
34cd0 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
34ce0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
34cf0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
34d00 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
34d10 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
34d20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
34d30 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
34d40 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
34d50 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
34d60 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
34d70 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
34d80 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
34d90 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
34da0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
34db0 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
34dc0 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
34dd0 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
34de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34df0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
34e00 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65 72   Constraint Oper
34e10 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  ator Codes.**.**
34e20 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64 65   These macros de
34e30 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77 65  fined the allowe
34e40 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  d values for the
34e50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64  .** [sqlite3_ind
34e60 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72  ex_info].aConstr
34e70 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e  aint[].op field.
34e80 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65 70    Each value rep
34e90 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70  resents.** an op
34ea0 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 20 70  erator that is p
34eb0 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72 61  art of a constra
34ec0 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65 20  int term in the 
34ed0 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 0a  wHERE clause of.
34ee0 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 74 20  ** a query that 
34ef0 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c 20  uses a [virtual 
34f00 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69  table]..*/.#defi
34f10 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
34f20 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20  CONSTRAINT_EQ   
34f30 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
34f40 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
34f50 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69  NT_GT    4.#defi
34f60 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
34f70 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20  CONSTRAINT_LE   
34f80 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
34f90 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
34fa0 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66  NT_LT    16.#def
34fb0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
34fc0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20  _CONSTRAINT_GE  
34fd0 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
34fe0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34ff0 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f  AINT_MATCH 64../
35000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
35010 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
35020 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
35030 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tation.**.** ^Th
35040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
35050 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
35060 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  r a new [virtual
35070 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e   table module] n
35080 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20  ame..** ^Module 
35090 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65  names must be re
350a0 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a  gistered before.
350b0 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65  ** creating a ne
350c0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
350d0 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75  ] using the modu
350e0 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73  le and before us
350f0 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73  ing a.** preexis
35100 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61  ting [virtual ta
35110 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64  ble] for the mod
35120 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ule..**.** ^The 
35130 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72  module name is r
35140 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65  egistered on the
35150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35160 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
35170 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
35180 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
35190 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  e name of the mo
351a0 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79  dule is given by
351b0 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20   the .** second 
351c0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
351d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
351e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
351f0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
35200 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76  tation of the [v
35210 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
35220 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75  ule].   ^The fou
35230 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
35240 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
35250 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69   client data poi
35260 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
35270 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69  sed through.** i
35280 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65  nto the [xCreate
35290 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
352a0 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
352b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
352c0 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e  dule.** when a n
352d0 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ew virtual table
352e0 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65   is be being cre
352f0 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61  ated or reinitia
35300 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lized..**.** ^Th
35310 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
35320 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74  _module_v2() int
35330 65 72 66 61 63 65 20 68 61 73 20 61 20 66 69 66  erface has a fif
35340 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  th parameter whi
35350 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
35360 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74  er to a destruct
35370 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65  or for the pClie
35380 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65  ntData.  ^SQLite
35390 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20   will.** invoke 
353a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
353b0 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69  unction (if it i
353c0 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e  s not NULL) when
353d0 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f   SQLite.** no lo
353e0 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20 70  nger needs the p
353f0 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74  ClientData point
35400 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  er.  ^The destru
35410 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  ctor will also.*
35420 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 66 20  * be invoked if 
35430 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
35440 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
35450 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  e_v2() fails..**
35460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
35470 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a  eate_module().**
35480 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
35490 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69  uivalent to sqli
354a0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
354b0 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
354c0 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  LL.** destructor
354d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
354e0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
354f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
35500 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35510 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
35520 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
35530 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
35540 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
35550 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
35560 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
35570 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
35580 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
35590 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
355a0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
355b0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
355c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
355d0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
355e0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
355f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
35600 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
35610 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
35630 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
35640 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
35650 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
35660 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
35670 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
35680 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
35690 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
356a0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
356b0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
356c0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
356d0 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
356e0 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
356f0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
35700 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
35710 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
35720 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
35730 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
35740 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
35750 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35760 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
35770 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
35780 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
35790 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a  sqlite3_vtab.**.
357a0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
357b0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
357c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
357d0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a  ses a subclass.*
357e0 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  * of this object
357f0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
35800 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
35810 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  ce.** of the [vi
35820 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45  rtual table].  E
35830 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c  ach subclass wil
35840 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64  l.** be tailored
35850 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
35860 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f   needs of the mo
35870 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
35880 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70  ion..** The purp
35890 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
358a0 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
358b0 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
358c0 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63  ds that are.** c
358d0 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64  ommon to all mod
358e0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
358f0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74  ons..**.** ^Virt
35900 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f  ual tables metho
35910 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72  ds can set an er
35920 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61  ror message by a
35930 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74  ssigning a.** st
35940 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
35950 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
35960 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73  ntf()] to zErrMs
35970 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
35980 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
35990 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
359a0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
359b0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
359c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
359d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
359e0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
359f0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
35a00 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72  ^After the error
35a10 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
35a20 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
35a30 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
35a40 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
35a50 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
35a60 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
35a70 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
35a80 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
35a90 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
35aa0 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
35ab0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
35ac0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
35ad0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
35ae0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
35af0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
35b00 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
35b10 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
35b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35b30 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20   NO LONGER USED 
35b40 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
35b50 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
35b60 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
35b70 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
35b80 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
35b90 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
35ba0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35bb0 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
35bc0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
35bd0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
35be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
35bf0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
35c00 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  sor Object.** KE
35c10 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
35c20 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72  vtab_cursor {vir
35c30 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
35c40 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  r}.**.** Every [
35c50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
35c60 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
35c70 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
35c80 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  lass of the.** f
35c90 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
35ca0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  re to describe c
35cb0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
35cc0 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76  t into the.** [v
35cd0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e  irtual table] an
35ce0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
35cf0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
35d00 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
35d10 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
35d20 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
35d30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ** [sqlite3_modu
35d40 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e  le.xOpen | xOpen
35d50 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
35d60 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64  module and are d
35d70 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74  estroyed.** by t
35d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  he [sqlite3_modu
35d90 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f  le.xClose | xClo
35da0 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72  se] method.  Cur
35db0 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a  sors are used.**
35dc0 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72   by the [xFilter
35dd0 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f  ], [xNext], [xEo
35de0 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61  f], [xColumn], a
35df0 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68  nd [xRowid] meth
35e00 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f  ods.** of the mo
35e10 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75  dule.  Each modu
35e20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35e30 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a  n will define.**
35e40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
35e50 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75  a cursor structu
35e60 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f  re to suit its o
35e70 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  wn needs..**.** 
35e80 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  This superclass 
35e90 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20  exists in order 
35ea0 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73  to define fields
35eb0 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74   of the cursor t
35ec0 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f  hat.** are commo
35ed0 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  n to all impleme
35ee0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72  ntations..*/.str
35ef0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
35f00 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69  _cursor {.  sqli
35f10 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b  te3_vtab *pVtab;
35f20 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c        /* Virtual
35f30 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63   table of this c
35f40 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69  ursor */.  /* Vi
35f50 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
35f60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
35f70 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
35f80 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
35f90 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
35fa0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20  PI3REF: Declare 
35fb0 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20  The Schema Of A 
35fc0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
35fd0 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74  .** ^The [xCreat
35fe0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
35ff0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
36000 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
36010 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
36020 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
36030 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
36040 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
36050 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
36060 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
36070 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
36080 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
36090 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lement..*/.int s
360a0 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
360b0 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
360c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
360d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
360e0 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
360f0 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
36100 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
36110 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  ^(Virtual tables
36120 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
36130 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
36140 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
36150 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
36160 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
36170 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
36180 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
36190 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
361a0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
361b0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
361c0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
361d0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
361e0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a  e overloaded.)^.
361f0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49  **.** ^(This API
36200 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
36210 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
36220 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
36230 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
36240 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
36250 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
36260 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
36270 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
36280 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
36290 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
362a0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
362b0 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54  s created.)^  ^T
362c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
362d0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
362e0 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
362f0 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
36300 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
36310 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
36320 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
36330 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
36340 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
36350 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
36360 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
36370 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  aceholder functi
36380 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
36390 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
363a0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
363b0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
363c0 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
363d0 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
363e0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
363f0 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
36400 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
36410 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
36420 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
36430 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
36440 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
36450 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
36460 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
36470 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
36480 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
36490 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
364a0 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
364b0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
364c0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
364d0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
364e0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
364f0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
36500 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
36510 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
36520 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
36530 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
36540 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
36550 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
36560 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
36570 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
36580 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
36590 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
365a0 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
365b0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
365c0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
365d0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
365e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42   KEYWORDS: {BLOB
365f0 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68   handle} {BLOB h
36600 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  andles}.**.** An
36610 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
36620 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
36630 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42  nts an open BLOB
36640 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71   on which.** [sq
36650 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
36660 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
36670 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70  OB I/O] can be p
36680 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62  erformed..** ^Ob
36690 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
366a0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
366b0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
366c0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64  open()].** and d
366d0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
366e0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
366f0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  )]..** ^The [sql
36700 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
36710 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
36720 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74  lob_write()] int
36730 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62  erfaces.** can b
36740 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f  e used to read o
36750 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75  r write small su
36760 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  bsections of the
36770 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b   BLOB..** ^The [
36780 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
36790 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
367a0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
367b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20   of the BLOB in 
367c0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  bytes..*/.typede
367d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
367e0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c  _blob sqlite3_bl
367f0 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ob;../*.** CAPI3
36800 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42  REF: Open A BLOB
36810 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c   For Incremental
36820 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69   I/O.**.** ^(Thi
36830 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65  s interfaces ope
36840 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ns a [BLOB handl
36850 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74  e | handle] to t
36860 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a  he BLOB located.
36870 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20  ** in row iRow, 
36880 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
36890 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
368a0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a  database zDb;.**
368b0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
368c0 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74   the same BLOB t
368d0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c  hat would be sel
368e0 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
368f0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
36900 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
36910 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
36920 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77  E [rowid] = iRow
36930 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  ;.** </pre>)^.**
36940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67  .** ^If the flag
36950 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
36960 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
36970 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
36980 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64   for read.** and
36990 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e   write access. ^
369a0 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
369b0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
369c0 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73  d for read acces
369d0 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74  s..** ^It is not
369e0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65   possible to ope
369f0 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  n a column that 
36a00 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e  is part of an in
36a10 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a  dex or primary .
36a20 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69  ** key for writi
36a30 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e  ng. ^If [foreign
36a40 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
36a50 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69  ] are enabled, i
36a60 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73  t is .** not pos
36a70 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
36a80 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
36a90 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20  art of a [child 
36aa0 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67  key] for writing
36ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
36ac0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
36ad0 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20  name is not the 
36ae0 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f  filename that co
36af0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61  ntains.** the da
36b00 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65  tabase but rathe
36b10 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  r the symbolic n
36b20 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
36b30 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65  ase that.** appe
36b40 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53  ars after the AS
36b50 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68   keyword when th
36b60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f  e database is co
36b70 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41  nnected using [A
36b80 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20  TTACH]..** ^For 
36b90 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
36ba0 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  e file, the data
36bb0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61  base name is "ma
36bc0 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d  in"..** ^For TEM
36bd0 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61  P tables, the da
36be0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
36bf0 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  temp"..**.** ^(O
36c00 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
36c10 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
36c20 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b  ed and the new [
36c30 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20  BLOB handle] is 
36c40 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
36c50 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65  pBlob. Otherwise
36c60 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
36c70 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
36c80 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a   *ppBlob is set.
36c90 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20  ** to be a null 
36ca0 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54  pointer.)^.** ^T
36cb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
36cc0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
36cd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f  connection] erro
36ce0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
36cf0 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
36d00 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
36d10 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
36d20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
36d30 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66  and related.** f
36d40 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20  unctions. ^Note 
36d50 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62  that the *ppBlob
36d60 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77   variable is alw
36d70 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  ays initialized 
36d80 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74  in a.** way that
36d90 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74   makes it safe t
36da0 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  o invoke [sqlite
36db0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20  3_blob_close()] 
36dc0 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65  on *ppBlob.** re
36dd0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
36de0 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
36df0 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  re of this routi
36e00 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ne..**.** ^(If t
36e10 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c  he row that a BL
36e20 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73  OB handle points
36e30 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20   to is modified 
36e40 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45  by an.** [UPDATE
36e50 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20  ], [DELETE], or 
36e60 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  by [ON CONFLICT]
36e70 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a   side-effects.**
36e80 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68   then the BLOB h
36e90 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20  andle is marked 
36ea0 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a  as "expired"..**
36eb0 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66   This is true if
36ec0 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   any column of t
36ed0 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65  he row is change
36ee0 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e  d, even a column
36ef0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74  .** other than t
36f00 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20  he one the BLOB 
36f10 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f  handle is open o
36f20 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  n.)^.** ^Calls t
36f30 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
36f40 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
36f50 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
36f60 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69  )] for.** a expi
36f70 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  red BLOB handle 
36f80 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74  fail with an ret
36f90 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
36fa0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e  ITE_ABORT]..** ^
36fb0 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e  (Changes written
36fc0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69   into a BLOB pri
36fd0 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65  or to the BLOB e
36fe0 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a  xpiring are not.
36ff0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
37000 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e  y the expiration
37010 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53   of the BLOB.  S
37020 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  uch changes will
37030 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63   eventually.** c
37040 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61  ommit if the tra
37050 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75  nsaction continu
37060 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
37070 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74  .)^.**.** ^Use t
37080 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
37090 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
370a0 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
370b0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
370c0 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
370d0 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61    ^The size of a
370e0 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
370f0 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
37100 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
37110 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
37120 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
37130 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
37140 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
37150 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
37160 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
37170 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37180 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
37190 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
371a0 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
371b0 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
371c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
371d0 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
371e0 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
371f0 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
37200 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
37210 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
37220 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
37230 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
37240 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
37250 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
37260 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
37270 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
37280 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
37290 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
372a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
372b0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a  ob_close()]..*/.
372c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
372d0 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
372e0 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
372f0 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
37300 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
37310 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
37320 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
37330 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
37340 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
37350 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
37360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37370 3a 20 4d 6f 76 65 20 61 20 42 4c 4f 42 20 48 61  : Move a BLOB Ha
37380 6e 64 6c 65 20 74 6f 20 61 20 4e 65 77 20 52 6f  ndle to a New Ro
37390 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  w.**.** ^This fu
373a0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
373b0 6f 20 6d 6f 76 65 20 61 6e 20 65 78 69 73 74 69  o move an existi
373c0 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 73  ng blob handle s
373d0 6f 20 74 68 61 74 20 69 74 20 70 6f 69 6e 74 73  o that it points
373e0 0a 2a 2a 20 74 6f 20 61 20 64 69 66 66 65 72 65  .** to a differe
373f0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 73 61  nt row of the sa
37400 6d 65 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  me database tabl
37410 65 2e 20 5e 54 68 65 20 6e 65 77 20 72 6f 77 20  e. ^The new row 
37420 69 73 20 69 64 65 6e 74 69 66 69 65 64 0a 2a 2a  is identified.**
37430 20 62 79 20 74 68 65 20 72 6f 77 69 64 20 76 61   by the rowid va
37440 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
37450 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37460 74 2e 20 4f 6e 6c 79 20 74 68 65 20 72 6f 77 20  t. Only the row 
37470 63 61 6e 20 62 65 0a 2a 2a 20 63 68 61 6e 67 65  can be.** change
37480 64 2e 20 5e 54 68 65 20 64 61 74 61 62 61 73 65  d. ^The database
37490 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  , table and colu
374a0 6d 6e 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  mn on which the 
374b0 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73 20 6f  blob handle is o
374c0 70 65 6e 0a 2a 2a 20 72 65 6d 61 69 6e 20 74 68  pen.** remain th
374d0 65 20 73 61 6d 65 2e 20 4d 6f 76 69 6e 67 20 61  e same. Moving a
374e0 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62 20  n existing blob 
374f0 68 61 6e 64 6c 65 20 74 6f 20 61 20 6e 65 77 20  handle to a new 
37500 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20 66 61  row can be.** fa
37510 73 74 65 72 20 74 68 61 6e 20 63 6c 6f 73 69 6e  ster than closin
37520 67 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 68  g the existing h
37530 61 6e 64 6c 65 20 61 6e 64 20 6f 70 65 6e 69 6e  andle and openin
37540 67 20 61 20 6e 65 77 20 6f 6e 65 2e 0a 2a 2a 0a  g a new one..**.
37550 2a 2a 20 5e 28 54 68 65 20 6e 65 77 20 72 6f 77  ** ^(The new row
37560 20 6d 75 73 74 20 6d 65 65 74 20 74 68 65 20 73   must meet the s
37570 61 6d 65 20 63 72 69 74 65 72 69 61 20 61 73 20  ame criteria as 
37580 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  for [sqlite3_blo
37590 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a 2a 2a 20 69  b_open()] -.** i
375a0 74 20 6d 75 73 74 20 65 78 69 73 74 20 61 6e 64  t must exist and
375b0 20 74 68 65 72 65 20 6d 75 73 74 20 62 65 20 65   there must be e
375c0 69 74 68 65 72 20 61 20 62 6c 6f 62 20 6f 72 20  ither a blob or 
375d0 74 65 78 74 20 76 61 6c 75 65 20 73 74 6f 72 65  text value store
375e0 64 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 6f 6d 69  d in.** the nomi
375f0 6e 61 74 65 64 20 63 6f 6c 75 6d 6e 2e 29 5e 20  nated column.)^ 
37600 5e 49 66 20 74 68 65 20 6e 65 77 20 72 6f 77 20  ^If the new row 
37610 69 73 20 6e 6f 74 20 70 72 65 73 65 6e 74 20 69  is not present i
37620 6e 20 74 68 65 20 74 61 62 6c 65 2c 20 6f 72 20  n the table, or 
37630 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
37640 74 20 63 6f 6e 74 61 69 6e 20 61 20 62 6c 6f 62  t contain a blob
37650 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65 2c 20   or text value, 
37660 6f 72 20 69 66 20 61 6e 6f 74 68 65 72 20 65 72  or if another er
37670 72 6f 72 20 6f 63 63 75 72 73 2c 20 61 6e 0a 2a  ror occurs, an.*
37680 2a 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63  * SQLite error c
37690 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
376a0 61 6e 64 20 74 68 65 20 62 6c 6f 62 20 68 61 6e  and the blob han
376b0 64 6c 65 20 69 73 20 63 6f 6e 73 69 64 65 72 65  dle is considere
376c0 64 20 61 62 6f 72 74 65 64 2e 0a 2a 2a 20 5e 41  d aborted..** ^A
376d0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ll subsequent ca
376e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
376f0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2c 20 5b 73  blob_read()], [s
37700 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
37710 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
37720 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28  te3_blob_reopen(
37730 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64  )] on an aborted
37740 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 6d 6d   blob handle imm
37750 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 0a  ediately return.
37760 2a 2a 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e  ** SQLITE_ABORT.
37770 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
37780 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64  ction sets the d
37790 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 65  atabase handle e
377a0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
377b0 73 73 61 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssage..*/.SQLITE
377c0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
377d0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
377e0 65 6f 70 65 6e 28 73 71 6c 69 74 65 33 5f 62 6c  eopen(sqlite3_bl
377f0 6f 62 20 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ob *, sqlite3_in
37800 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
37810 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42  I3REF: Close A B
37820 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  LOB Handle.**.**
37830 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e   ^Closes an open
37840 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a   [BLOB handle]..
37850 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61  **.** ^Closing a
37860 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
37870 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
37880 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
37890 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
378a0 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
378b0 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
378c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
378d0 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
378e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
378f0 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f  on is in [autoco
37900 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e  mmit mode]..** ^
37910 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
37920 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
37930 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
37940 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
37950 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
37960 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
37970 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a   they will fit..
37980 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20  **.** ^(Closing 
37990 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66  the BLOB often f
379a0 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65  orces the change
379b0 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b  s.** out to disk
379c0 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49   and so if any I
379d0 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c  /O errors occur,
379e0 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c   they will likel
379f0 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68  y occur.** at th
37a00 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  e time when the 
37a10 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20  BLOB is closed. 
37a20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74   Any errors that
37a30 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a   occur during.**
37a40 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70   closing are rep
37a50 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a  orted as a non-z
37a60 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ero return value
37a70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  .)^.**.** ^(The 
37a80 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
37a90 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
37aa0 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
37ab0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
37ac0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
37ad0 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
37ae0 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a  l closed.)^.**.*
37af0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
37b00 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e  routine with a n
37b10 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63  ull pointer (suc
37b20 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65  h as would be re
37b30 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66  turned.** by a f
37b40 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73  ailed call to [s
37b50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
37b60 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65  ()]) is a harmle
37b70 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
37b80 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c   sqlite3_blob_cl
37b90 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ose(sqlite3_blob
37ba0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
37bb0 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
37bc0 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e   Size Of An Open
37bd0 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   BLOB.**.** ^Ret
37be0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e  urns the size in
37bf0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
37c00 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  OB accessible vi
37c10 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73  a the .** succes
37c20 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42  sfully opened [B
37c30 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69  LOB handle] in i
37c40 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
37c50 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65  .  ^The.** incre
37c60 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20  mental blob I/O 
37c70 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c  routines can onl
37c80 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72  y read or overwr
37c90 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a  iting existing.*
37ca0 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20  * blob content; 
37cb0 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e  they cannot chan
37cc0 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
37cd0 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   blob..**.** Thi
37ce0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
37cf0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
37d00 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
37d10 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
37d20 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
37d30 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
37d40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
37d50 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
37d60 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
37d70 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
37d80 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
37d90 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
37da0 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
37db0 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
37dc0 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
37dd0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
37de0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
37df0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e   behavior..*/.in
37e00 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62  t sqlite3_blob_b
37e10 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f  ytes(sqlite3_blo
37e20 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
37e30 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61  I3REF: Read Data
37e40 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63   From A BLOB Inc
37e50 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
37e60 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
37e70 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64   is used to read
37e80 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70   data from an op
37e90 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
37ea0 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65   into a.** calle
37eb0 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
37ec0 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61  r. N bytes of da
37ed0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  ta are copied in
37ee0 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66  to buffer Z.** f
37ef0 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  rom the open BLO
37f00 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
37f10 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e  ffset iOffset.)^
37f20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65  .**.** ^If offse
37f30 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
37f40 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
37f50 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
37f60 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
37f70 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
37f80 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
37f90 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66  ta is read.  ^If
37fa0 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73   N or iOffset is
37fb0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
37fc0 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ro, [SQLITE_ERRO
37fd0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
37fe0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
37ff0 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65  ad..** ^The size
38000 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e   of the blob (an
38010 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
38020 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
38030 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
38040 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
38050 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
38060 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
38070 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
38080 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  An attempt to re
38090 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72  ad from an expir
380a0 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
380b0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
380c0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
380d0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
380e0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65  **.** ^(On succe
380f0 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ss, sqlite3_blob
38100 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  _read() returns 
38110 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74  SQLITE_OK..** Ot
38120 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72  herwise, an [err
38130 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
38140 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
38150 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
38160 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
38170 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
38180 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
38190 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
381a0 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
381b0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
381c0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
381d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
381e0 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
381f0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
38200 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
38210 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
38220 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
38230 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
38240 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
38250 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
38260 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
38270 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
38280 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
38290 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
382a0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a  _blob_write()]..
382b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
382c0 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
382d0 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a  _blob *, void *Z
382e0 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66  , int N, int iOf
382f0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
38300 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61  PI3REF: Write Da
38310 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
38320 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
38330 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
38340 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
38350 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
38360 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
38370 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
38380 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
38390 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66  fer. ^N bytes of
383a0 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
383b0 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
383c0 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f   Z.** into the o
383d0 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
383e0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
383f0 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  fset..**.** ^If 
38400 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
38410 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
38420 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77  first argument w
38430 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
38440 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68  r.** writing (th
38450 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
38460 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  r to [sqlite3_bl
38470 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a  ob_open()] was z
38480 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75  ero),.** this fu
38490 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
384a0 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
384b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
384c0 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20  nction may only 
384d0 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65  modify the conte
384e0 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b  nts of the BLOB;
384f0 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f   it is.** not po
38500 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61  ssible to increa
38510 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  se the size of a
38520 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73   BLOB using this
38530 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66   API..** ^If off
38540 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
38550 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
38560 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
38570 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
38580 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
38590 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
385a0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
385b0 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65    ^If N is.** le
385c0 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
385d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
385e0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
385f0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
38600 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  ** The size of t
38610 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e  he BLOB (and hen
38620 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
38630 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
38640 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
38650 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
38660 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
38670 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
38680 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
38690 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74  tempt to write t
386a0 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  o an expired [BL
386b0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
386c0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
386d0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
386e0 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74  E_ABORT].  ^Writ
386f0 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74  es to the BLOB t
38700 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20  hat occurred.** 
38710 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42  before the [BLOB
38720 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64   handle] expired
38730 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20   are not rolled 
38740 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65  back by the.** e
38750 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
38760 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20   handle, though 
38770 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20  of course those 
38780 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a  changes might.**
38790 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77   have been overw
387a0 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74  ritten by the st
387b0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70  atement that exp
387c0 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61  ired the BLOB ha
387d0 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74  ndle.** or by ot
387e0 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  her independent 
387f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
38800 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
38810 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
38820 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  te() returns SQL
38830 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
38840 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
38850 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
38860 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
38870 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
38880 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ^.**.** This rou
38890 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
388a0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
388b0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
388c0 6e 20 63 72 65 61