/ Hex Artifact Content
Login

Artifact 8ee5a78674f9b78a59a0313197a46892204e3407:


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 2a 0a 2a  me systems..**.*
7fb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7fc0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
7fd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7fe0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
7ff0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8010: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8020: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8030: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8040: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8060: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8070: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8080: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8090: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
80a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
80b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
80c0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
80d0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
80e0: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
80f0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
8100: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8110: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
8120: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
8130: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
8140: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8150: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
8160: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
8170: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8180: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
8190: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
81a0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
81b0: 20 20 37 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    7.../*.** CAPI
81c0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
81d0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
81e0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
81f0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
8200: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
8210: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
8220: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
8230: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
8240: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
8250: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
8260: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
8270: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
8280: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
8290: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
82a0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
82b0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
82c0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
82d0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
82e0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
82f0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
8300: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
8310: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
8320: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
8330: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
8340: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
8350: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
8360: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
8370: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
8380: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
8390: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
83a0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
83b0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
83c0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
83d0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
83e0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
83f0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
8400: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
8410: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
8420: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
8430: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
8440: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
8450: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
8460: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
8470: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
8480: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
8490: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
84a0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
84b0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
84c0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
84d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
84e0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
84f0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
8500: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
8510: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
8520: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
8530: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
8540: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
8550: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
8560: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
8570: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
8580: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
8590: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
85a0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
85b0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
85c0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
85d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
85e0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
85f0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
8600: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
8610: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
8620: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
8630: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
8640: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
8650: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
8660: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
8670: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
8680: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
8690: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
86a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
86b0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
86c0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
86d0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
86e0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
86f0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
8700: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
8710: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
8720: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
8730: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
8740: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
8750: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
8760: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
8770: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
8780: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
8790: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
87a0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
87b0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
87c0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
87d0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
87e0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
87f0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
8800: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
8810: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
8820: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
8830: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
8840: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
8850: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
8860: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
8870: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
8880: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
8890: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
88a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
88b0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
88c0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
88d0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
88e0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
88f0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
8900: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
8910: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
8920: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
8930: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
8940: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  modules..**.** ^
8950: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
8960: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
8970: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8980: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
8990: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
89a0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
89b0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
89c0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
89d0: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
89e0: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
89f0: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
8a00: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
8a10: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8a20: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
8a30: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
8a40: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
8a50: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
8a60: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61  ore than.** 10 a
8a70: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
8a80: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
8a90: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
8aa0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
8ab0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
8ac0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
8ad0: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
8ae0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
8af0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
8b00: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
8b10: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
8b20: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
8b30: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
8b40: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
8b50: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
8b60: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
8b70: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
8b80: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
8b90: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
8ba0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8bb0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
8bc0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8bd0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8be0: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
8bf0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8c00: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8c10: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
8c20: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8c30: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8c40: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8c50: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8c60: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8c70: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
8c80: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8c90: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8ca0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8cb0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8cc0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8cd0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8ce0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8cf0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8d00: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8d10: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8d20: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8d30: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8d40: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8d50: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8d70: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
8d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8d90: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8da0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8db0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8dc0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8dd0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8de0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8df0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8e00: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8e10: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8e20: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
8e30: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
8e40: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8e50: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8e60: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
8e70: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
8e80: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
8e90: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
8ea0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8eb0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
8ec0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8ed0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
8ee0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ef0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
8f00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8f10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
8f20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
8f30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
8f40: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
8f50: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
8f60: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
8f70: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8f80: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
8f90: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8fa0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
8fb0: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
8fc0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
8fd0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
8fe0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
8ff0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
9000: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
9010: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
9020: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
9030: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
9040: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
9050: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
9060: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
9070: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
9080: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
9090: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
90a0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
90b0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
90c0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
90d0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
90e0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
90f0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
9100: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
9110: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
9120: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
9130: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
9140: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
9150: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
9160: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
9170: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
9180: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
9190: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
91a0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
91b0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
91c0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
91d0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
91e0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
91f0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
9200: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
9210: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
9220: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
9230: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9240: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
9250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
9260: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
9270: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
9280: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
9290: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
92a0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
92b0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
92c0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
92d0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
92e0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
92f0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
9300: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
9310: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
9320: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
9330: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
9340: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
9350: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
9360: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
9370: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
9380: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
9390: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
93a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
93b0: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
93c0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
93d0: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
93e0: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
93f0: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
9400: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
9410: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
9420: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
9430: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
9440: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
9450: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
9460: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
9470: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9480: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
9490: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
94a0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
94b0: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
94c0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
94d0: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
94e0: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
94f0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
9500: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
9510: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
9520: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
9530: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
9540: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
9550: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
9560: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
9570: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
9580: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9590: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
95a0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
95b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
95c0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
95d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
95e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
95f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
9600: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
9610: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
9620: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
9630: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
9640: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
9650: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
9660: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
9670: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
9680: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
9690: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
96a0: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
96b0: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
96c0: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
96d0: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
96e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
96f0: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
9700: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
9710: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
9720: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
9730: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
9740: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
9750: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
9760: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ..**.** ^The fla
9770: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9780: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
9790: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
97a0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
97b0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
97c0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
97d0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
97e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
97f0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
9800: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
9810: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
9820: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9830: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
9840: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
9850: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
9860: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
9870: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
9880: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
9890: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
98a0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
98b0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
98c0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
98d0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
98e0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
98f0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9900: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9910: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9920: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9930: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9940: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
9950: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9960: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9970: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
9980: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
9990: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
99a0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
99b0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
99c0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
99d0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
99e0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
99f0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9a00: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9a10: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9a20: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9a30: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9a40: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9a50: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9a60: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
9a70: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9a80: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
9a90: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
9aa0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9ab0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9ac0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9ad0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9ae0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9af0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9b00: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9b10: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9b20: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9b30: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9b40: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
9b50: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
9b60: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
9b70: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
9b80: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
9b90: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
9ba0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9bb0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9bc0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9bd0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9be0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9bf0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9c00: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9c10: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9c20: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9c30: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
9c40: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
9c50: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
9c60: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
9c70: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
9c80: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
9c90: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
9ca0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
9cb0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
9cc0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
9cd0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9ce0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9cf0: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9d00: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9d10: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9d20: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9d30: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9d40: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
9d50: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9d60: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
9d70: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
9d80: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
9d90: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
9da0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
9db0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
9dc0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
9dd0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9de0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9df0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9e00: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9e10: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9e20: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9e30: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9e40: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9e50: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9e60: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
9e70: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
9e80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
9e90: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
9ea0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
9eb0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
9ec0: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
9ed0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
9ee0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
9ef0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
9f00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
9f10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
9f20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
9f30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
9f40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
9f50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
9f60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
9f70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
9f80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
9f90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
9fa0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
9fb0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
9fc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
9fd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
9fe0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
9ff0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a000: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a010: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a020: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a030: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a040: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a050: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a060: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a070: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a080: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a090: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a0a0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a0b0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a0c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a0d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a0e0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a0f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a100: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a110: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a120: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a130: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a140: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a150: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a160: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a170: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a180: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a190: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a1a0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a1b0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
a1c0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
a1d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
a1e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a1f0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
a200: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
a210: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a220: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
a230: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
a240: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
a250: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
a260: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
a270: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
a280: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
a290: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
a2a0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
a2b0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
a2c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
a2d0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
a2e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
a2f0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
a300: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a310: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a320: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
a330: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
a340: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
a350: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
a360: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
a370: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
a380: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
a390: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
a3a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
a3b0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
a3c0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
a3d0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
a3e0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
a3f0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
a400: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
a410: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
a420: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
a430: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
a440: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
a450: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
a460: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
a470: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
a480: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
a490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
a4a0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
a4b0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
a4c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
a4d0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a4e0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a4f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a500: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a510: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a520: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a530: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a540: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a550: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a560: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a570: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a580: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a590: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a5a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a5b0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a5c0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a5d0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a5e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a5f0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a600: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a610: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a620: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a630: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a640: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a650: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a660: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a670: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a680: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a690: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a6a0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a6b0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a6c0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a6d0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a6e0: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a6f0: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a700: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a710: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a720: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a730: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a740: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a750: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a760: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a770: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a780: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a790: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a7a0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a7b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a7c0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a7d0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a7e0: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a7f0: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a800: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a810: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a830: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a850: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a860: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
a870: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
a880: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a8a0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
a8b0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
a8c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
a8d0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
a8e0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
a8f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a900: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
a910: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
a920: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
a930: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
a940: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
a950: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
a960: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
a970: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
a980: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
a990: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
a9a0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
a9b0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
a9c0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a9d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a9e0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
a9f0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
aa00: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
aa10: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
aa20: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
aa30: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
aa40: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
aa50: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
aa60: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
aa70: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
aa80: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
aa90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
aaa0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
aab0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
aac0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
aad0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
aae0: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
aaf0: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
ab00: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
ab10: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
ab20: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
ab30: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
ab40: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
ab50: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
ab60: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
ab70: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ab80: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ab90: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
aba0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
abb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
abc0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
abd0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
abe0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
abf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ac00: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ac10: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
ac20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
ac30: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
ac40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
ac50: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
ac60: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
ac70: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
ac80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ac90: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
aca0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
acb0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
acc0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
acd0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
ace0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
acf0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
ad00: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
ad10: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
ad20: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
ad30: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
ad40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ad50: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
ad60: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
ad70: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
ad80: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
ad90: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ada0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
adb0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
adc0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
add0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
ade0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
adf0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
ae00: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
ae10: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
ae20: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
ae30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ae40: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
ae50: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
ae60: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
ae70: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
ae80: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
ae90: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
aea0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
aeb0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
aec0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
aed0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
aee0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
aef0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
af00: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
af10: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
af20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
af30: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
af40: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
af50: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
af60: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
af70: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
af80: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
af90: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
afa0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
afb0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
afc0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
afd0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
afe0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
aff0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
b000: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b010: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
b020: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
b030: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
b040: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
b050: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
b060: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
b070: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
b080: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
b090: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
b0a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
b0b0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
b0c0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
b0d0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
b0e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
b0f0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
b100: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
b110: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
b120: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
b130: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
b140: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
b150: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
b160: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
b170: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
b180: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
b190: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
b1a0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
b1b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b1c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b1d0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
b1e0: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
b1f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
b200: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
b210: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b220: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
b230: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
b240: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
b250: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
b260: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
b270: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
b280: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
b290: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
b2a0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
b2b0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
b2c0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
b2d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
b2e0: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
b2f0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
b300: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
b310: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
b320: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
b330: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
b340: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
b350: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
b360: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
b370: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
b380: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
b390: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
b3a0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
b3b0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
b3c0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
b3d0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
b3e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b3f0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
b400: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
b410: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
b420: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
b430: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
b440: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
b450: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
b460: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
b470: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
b480: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b490: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b4a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b4b0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
b4c0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
b4d0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b4e0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b4f0: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b500: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b510: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b520: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b530: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b540: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b550: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b560: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b570: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b580: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b590: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b5a0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b5b0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b5c0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b5d0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b5e0: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b5f0: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b600: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b610: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b620: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b630: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b640: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b650: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b660: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b670: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b680: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b690: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b6a0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b6b0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b6c0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b6d0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b6e0: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b6f0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b700: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b710: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b720: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b730: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b740: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b750: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b760: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b770: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b780: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b790: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b7a0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b7b0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b7c0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b7d0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b7e0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b7f0: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b800: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b810: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b820: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b830: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b840: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b850: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b860: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
b870: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
b880: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b890: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
b8a0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
b8b0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
b8c0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
b8d0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
b8e0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
b8f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
b900: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
b910: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
b920: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
b930: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
b940: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
b950: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
b960: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
b970: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
b980: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
b990: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
b9a0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
b9b0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
b9c0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
b9d0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
b9e0: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
b9f0: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
ba00: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
ba10: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
ba20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ba30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
ba40: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
ba50: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
ba60: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
ba70: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
ba80: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
ba90: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
baa0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
bab0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
bac0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bad0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
bae0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
baf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bb00: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
bb10: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
bb20: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
bb30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
bb40: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
bb50: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
bb60: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
bb70: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
bb80: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
bb90: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
bba0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
bbb0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
bbc0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
bbd0: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
bbe0: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
bbf0: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
bc00: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
bc10: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
bc20: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
bc30: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
bc40: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
bc50: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
bc60: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
bc70: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
bc80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
bc90: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
bca0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bcb0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
bcc0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
bcd0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
bce0: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
bcf0: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
bd00: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
bd10: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
bd20: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
bd30: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
bd40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
bd50: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
bd60: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
bd70: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
bd80: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
bd90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bda0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
bdb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
bdc0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
bdd0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
bde0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
bdf0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
be00: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
be10: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
be20: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
be30: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
be40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
be50: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
be60: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
be70: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
be80: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
be90: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
bea0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
beb0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
bec0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
bed0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
bee0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
bef0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
bf00: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
bf10: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
bf20: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
bf30: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
bf40: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
bf50: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
bf60: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
bf70: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
bf80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bf90: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
bfa0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
bfb0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
bfc0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
bfd0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
bfe0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
bff0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
c000: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
c010: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
c020: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
c030: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
c040: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
c050: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
c060: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
c070: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
c080: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
c090: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
c0a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c0b0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
c0c0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
c0d0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
c0e0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
c0f0: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
c100: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
c110: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
c120: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
c130: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
c140: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
c150: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
c160: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
c170: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
c180: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
c190: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
c1a0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
c1b0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
c1c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
c1d0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
c1e0: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
c1f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c200: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
c210: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
c220: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
c230: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
c240: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
c250: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
c260: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
c270: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
c280: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
c290: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
c2a0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
c2b0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
c2c0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
c2d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c2e0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
c2f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
c300: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c310: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
c320: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
c330: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
c340: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
c350: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
c360: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
c370: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
c380: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
c390: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
c3a0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
c3b0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
c3c0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
c3d0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
c3e0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c3f0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
c400: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c410: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
c420: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c430: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
c440: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
c450: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
c460: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
c470: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
c480: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
c490: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
c4a0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
c4b0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
c4c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c4d0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c4e0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c4f0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c500: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c510: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c520: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c530: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c540: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c550: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c560: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c570: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c580: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c590: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c5a0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c5b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c5c0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c5d0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c5e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c5f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c600: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c610: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c620: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c630: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c640: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c650: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c660: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c670: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c680: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c690: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c6a0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c6b0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c6c0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c6d0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c6e0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c6f0: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c700: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c710: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c720: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c730: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c740: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c750: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c760: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c770: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c780: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c790: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c7a0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c7b0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c7c0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c7d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c7e0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c7f0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c800: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c810: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c820: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c830: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c840: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c850: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c860: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
c870: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
c880: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c890: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
c8a0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
c8b0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
c8c0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
c8d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
c8e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c8f0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
c900: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
c910: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
c920: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
c930: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
c940: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
c950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c960: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
c970: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c980: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
c990: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
c9a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c9b0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
c9c0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
c9d0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
c9e0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c9f0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
ca00: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
ca10: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
ca20: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
ca30: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
ca40: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
ca50: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
ca60: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
ca70: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
ca80: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
ca90: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
caa0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
cab0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
cac0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
cad0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
cae0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
caf0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
cb00: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
cb10: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
cb20: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
cb30: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
cb40: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
cb50: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
cb60: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
cb70: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
cb80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cb90: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
cba0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
cbb0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
cbc0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
cbd0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
cbe0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
cbf0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
cc00: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
cc10: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
cc20: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
cc30: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
cc40: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
cc50: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
cc60: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
cc70: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
cc80: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
cc90: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
cca0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
ccb0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
ccc0: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
ccd0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
cce0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
ccf0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
cd00: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
cd10: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
cd20: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
cd30: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
cd40: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
cd50: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
cd60: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
cd70: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
cd80: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
cd90: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
cda0: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
cdb0: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
cdc0: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
cdd0: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
cde0: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
cdf0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ce00: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ce10: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
ce20: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
ce30: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
ce40: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
ce50: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
ce60: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
ce70: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
ce80: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
ce90: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
cea0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
ceb0: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
cec0: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
ced0: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
cee0: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
cef0: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
cf00: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
cf10: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
cf20: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
cf30: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
cf40: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
cf50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
cf60: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
cf70: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
cf80: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
cf90: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cfa0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
cfb0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
cfc0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
cfd0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
cfe0: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
cff0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
d000: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
d010: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
d020: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
d030: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d040: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
d050: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
d060: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
d070: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d080: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
d090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
d0a0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
d0b0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
d0c0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
d0d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
d0e0: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
d0f0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
d100: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
d110: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
d120: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
d130: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
d140: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
d150: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d160: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
d170: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
d180: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
d190: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
d1a0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
d1b0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
d1c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
d1d0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
d1e0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
d1f0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
d200: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
d210: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
d220: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
d230: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
d240: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
d250: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
d260: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
d270: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
d280: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
d290: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
d2a0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
d2b0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
d2c0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
d2d0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
d2e0: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
d2f0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
d300: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
d310: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
d320: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
d330: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
d340: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
d350: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
d360: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
d370: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
d380: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
d390: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
d3a0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
d3b0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
d3c0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
d3d0: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
d3e0: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
d3f0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
d400: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d410: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
d420: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
d430: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
d440: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
d450: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
d460: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
d470: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
d480: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
d490: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
d4a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d4b0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
d4c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d4d0: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d4e0: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d4f0: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d500: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d510: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d520: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d530: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d540: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d550: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d560: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d570: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d580: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d590: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d5a0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d5b0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d5c0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d5d0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d5e0: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d5f0: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d600: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d610: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d620: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d630: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d640: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d650: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d660: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d670: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d680: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d690: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d6a0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d6b0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d6c0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d6d0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d6e0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d6f0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d700: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d710: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d720: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d740: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d750: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d760: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d770: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d780: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d790: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d7a0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d7b0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d7c0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d7d0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d7e0: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d7f0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d800: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d810: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d820: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d830: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d840: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d850: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d860: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
d870: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d880: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
d890: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
d8a0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
d8b0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d8c0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
d8d0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
d8e0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
d8f0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
d900: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
d910: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d920: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
d930: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
d940: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
d970: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
d980: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d990: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
d9a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d9b0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
d9c0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
d9d0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d9e0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
d9f0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
da00: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
da10: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
da20: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
da30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
da40: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
da50: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
da60: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
da70: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
da80: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
da90: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
daa0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
dab0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
dac0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
dad0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dae0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
daf0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
db00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
db10: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
db20: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
db30: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
db40: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
db50: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
db60: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
db70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
db80: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
db90: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
dba0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
dbb0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
dbc0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
dbd0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
dbe0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
dbf0: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
dc00: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
dc10: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dc20: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dc30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dc40: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dc50: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc60: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc70: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc80: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
dc90: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
dca0: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
dcb0: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
dcc0: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
dcd0: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
dce0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
dcf0: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
dd00: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
dd10: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
dd20: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
dd30: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
dd40: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
dd50: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
dd60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
dd70: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
dd80: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
dd90: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
dda0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
ddb0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
ddc0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
ddd0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
dde0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
ddf0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
de00: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
de10: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
de20: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
de30: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
de40: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
de50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
de60: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
de70: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
de80: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
de90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dea0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
deb0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
dec0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
ded0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
dee0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
def0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
df00: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
df10: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
df20: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
df30: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
df40: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
df50: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
df60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
df70: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
df80: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
df90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
dfa0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
dfb0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
dfc0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
dfd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
dfe0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
dff0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e000: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
e010: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
e020: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
e030: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e040: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
e050: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
e060: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
e070: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
e080: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
e090: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e0a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
e0b0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e0c0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
e0d0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
e0e0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
e0f0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
e100: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
e110: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
e120: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
e130: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
e140: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
e150: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
e160: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
e170: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
e180: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
e190: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e1a0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
e1b0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
e1c0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
e1d0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
e1e0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
e1f0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
e200: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
e210: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e220: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
e230: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
e240: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
e250: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
e260: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e270: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e280: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
e290: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
e2a0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
e2b0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
e2c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e2d0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
e2e0: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
e2f0: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
e300: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
e310: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
e320: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
e330: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e340: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e350: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e360: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e370: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e380: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e390: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e3a0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
e3b0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
e3c0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
e3d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e3e0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
e3f0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
e400: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
e410: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
e420: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
e430: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e440: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e450: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e460: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
e470: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
e480: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e490: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
e4a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e4b0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
e4c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
e4d0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e4e0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e4f0: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e500: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e510: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e520: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e530: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e540: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e550: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e560: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e570: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e580: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e590: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e5a0: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e5b0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e5c0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e5d0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e5e0: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e5f0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e600: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e610: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e620: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e630: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e640: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e650: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e660: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e670: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e680: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e690: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e6a0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e6b0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e6c0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e6d0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e6e0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e6f0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e700: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e710: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e720: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e730: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e740: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e750: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e760: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e770: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e780: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e790: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e7a0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e7b0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e7c0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e7d0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e7e0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e7f0: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e800: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e810: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e820: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e830: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e840: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e850: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e860: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
e870: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
e880: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e890: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
e8a0: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
e8b0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e8c0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
e8d0: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
e8e0: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
e8f0: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
e900: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
e910: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
e920: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
e930: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
e940: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
e950: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
e960: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e970: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
e980: 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
e990: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
e9a0: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
e9b0: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
e9c0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e9d0: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
e9e0: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
e9f0: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
ea00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
ea10: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
ea20: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
ea30: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
ea40: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
ea50: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
ea60: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
ea70: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
ea80: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ea90: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
eaa0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
eab0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
eac0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
ead0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
eae0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
eaf0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
eb00: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
eb10: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
eb20: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
eb30: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
eb40: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
eb50: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20  hich the scrach 
eb60: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
eb70: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
eb80: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
eb90: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
eba0: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
ebb0: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
ebc0: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
ebd0: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
ebe0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
ebf0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
ec00: 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
ec10: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ec20: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
ec30: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
ec40: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
ec50: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
ec60: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
ec70: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
ec80: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
ec90: 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
eca0: 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
ecb0: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
ecc0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
ecd0: 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
ece0: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
ecf0: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
ed00: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
ed10: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
ed20: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
ed30: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
ed40: 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
ed50: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
ed60: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
ed70: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
ed80: 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
ed90: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
eda0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
edb0: 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
edc0: 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
edd0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ede0: 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
edf0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
ee00: 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
ee10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ee20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ee30: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
ee40: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
ee50: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
ee60: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
ee70: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
ee80: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
ee90: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
eea0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
eeb0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
eec0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
eed0: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
eee0: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
eef0: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
ef00: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
ef10: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
ef20: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
ef30: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
ef40: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
ef50: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
ef60: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
ef70: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
ef80: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
ef90: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
efa0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
efb0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
efc0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
efd0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
efe0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
eff0: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
f000: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
f010: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
f020: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
f030: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
f040: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
f050: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
f060: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
f070: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
f080: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
f090: 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
f0a0: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
f0b0: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
f0c0: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
f0d0: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
f0e0: 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
f0f0: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
f100: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
f110: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
f120: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
f130: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
f140: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
f150: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
f160: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
f170: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
f180: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
f190: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
f1a0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
f1b0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
f1c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
f1d0: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
f1e0: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
f1f0: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
f200: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
f210: 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
f220: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
f230: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
f240: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
f250: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
f260: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
f270: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
f280: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
f290: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
f2a0: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
f2b0: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
f2c0: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
f2d0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
f2e0: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
f2f0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
f300: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
f310: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
f320: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
f330: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
f340: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f350: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
f360: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
f370: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
f380: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
f390: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
f3a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
f3b0: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
f3c0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
f3d0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f3e0: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
f3f0: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
f400: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f410: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
f420: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f430: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
f440: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
f450: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
f460: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
f470: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
f480: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
f490: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
f4a0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
f4b0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
f4c0: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
f4d0: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
f4e0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f4f0: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
f500: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
f510: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
f520: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
f530: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f540: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
f550: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
f560: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
f570: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
f580: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
f590: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
f5a0: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
f5b0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
f5c0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
f5d0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
f5e0: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
f5f0: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
f600: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
f610: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
f620: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
f630: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
f640: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
f650: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
f660: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
f670: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
f680: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
f690: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
f6a0: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
f6b0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f6c0: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
f6d0: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
f6e0: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
f6f0: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
f700: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f710: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f720: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
f730: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f740: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f750: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f760: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f770: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f780: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f790: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
f7a0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
f7b0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
f7c0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
f7d0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
f7e0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
f7f0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
f800: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
f810: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
f820: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
f830: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
f840: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
f850: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f860: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
f870: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
f880: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
f890: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f8a0: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
f8b0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
f8c0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
f8d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f8e0: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
f8f0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
f900: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
f910: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
f920: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
f930: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
f940: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
f950: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
f960: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f970: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
f980: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
f990: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
f9a0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
f9b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f9c0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
f9d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f9e0: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
f9f0: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
fa00: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
fa10: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
fa20: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
fa30: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
fa40: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
fa50: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
fa60: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
fa70: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
fa80: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
fa90: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
faa0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
fab0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
fac0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
fad0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
fae0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
faf0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
fb00: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
fb10: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
fb20: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
fb30: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
fb40: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
fb50: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
fb60: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
fb70: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
fb80: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
fb90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
fba0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
fbb0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
fbc0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
fbd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fbe0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
fbf0: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
fc00: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
fc10: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
fc20: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
fc30: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
fc40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
fc50: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
fc60: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
fc70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fc80: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
fc90: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
fca0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fcb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fcc0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
fcd0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fce0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
fcf0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
fd00: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
fd10: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
fd20: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
fd30: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
fd40: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
fd50: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
fd60: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
fd70: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fd80: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
fd90: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
fda0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
fdb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
fdc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
fdd0: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
fde0: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
fdf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
fe00: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
fe10: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
fe20: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
fe30: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
fe40: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
fe50: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
fe60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
fe70: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
fe80: 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
fe90: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
fea0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
feb0: 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
fec0: 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
fed0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fee0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
fef0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
ff00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
ff10: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
ff20: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
ff30: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
ff40: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
ff50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
ff60: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
ff70: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
ff80: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
ff90: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
ffa0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
ffb0: 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
ffc0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
ffd0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
ffe0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
fff0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
10000 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
10010 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
10020 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
10030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10040 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10050 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10060 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10070 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
10080 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
10090 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
100a0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
100b0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
100c0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
100d0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
100e0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
100f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
10110 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
10120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10130 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
10140 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
10150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
10160 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
10170 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
10180 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
10190 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
101a0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
101b0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
101c0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
101d0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
101e0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
101f0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
10200 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
10210 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
10220 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
10230 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
10240 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
10250 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
10260 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
10270 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
10280 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
10290 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
102a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
102b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
102c0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
102d0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
102e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
102f0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
10300 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
10310 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
10320 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
10330 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
10340 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
10350 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
10360 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
10370 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
10380 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10390 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
103a0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
103b0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
103c0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
103d0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
103e0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
103f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10400 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
10410 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
10420 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
10430 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
10440 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
10450 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
10460 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
10470 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
10480 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
10490 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
104a0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
104b0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
104c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
104d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
104e0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
104f0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
10500 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
10510 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
10520 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10530 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
10540 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
10550 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
10560 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
10570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10580 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10590 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
105a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
105b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
105c0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
105d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
105e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
105f0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
10600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10610 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10620 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
10630 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10640 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10660 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
10670 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10680 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
10690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
106a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
106b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
106c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
106d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
106e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
106f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
10700 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
10710 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10720 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
10730 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
10740 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
10750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10760 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10770 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
10780 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
10790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
107a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
107b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
107c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
107d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
107e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
107f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
10800 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10810 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
10820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
10830 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
10840 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
10850 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
10860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10870 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
10880 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
10890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
108a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
108b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
108c0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
108d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
108e0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
108f0 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
10900 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
10910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10920 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
10930 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
10940 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  c, void* */../*.
10950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
10960 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
10970 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10980 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
10990 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
109a0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
109b0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
109c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
109d0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
109e0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
109f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10a00 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10a10 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10a20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10a30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10a40 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10a50 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10a60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10a70 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10a80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10a90 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10aa0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10ab0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10ac0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10ad0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10ae0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
10af0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10b00 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
10b10 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
10b20 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10b30 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10b40 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10b50 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10b60 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10b70 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10b80 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10b90 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10ba0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10bb0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
10bc0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10bd0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
10be0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
10bf0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
10c00 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
10c10 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10c20 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
10c30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10c40 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10c50 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
10c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
10c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
10c80 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
10c90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
10ca0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10cb0 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
10cc0 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79  ter to an memory
10cd0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
10ce0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
10cf0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
10d00 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
10d10 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
10d20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10d30 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
10d40 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
10d50 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
10d60 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
10d70 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
10d80 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
10d90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
10da0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
10db0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
10dc0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
10dd0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
10de0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
10df0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
10e00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
10e10 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
10e20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
10e30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10e40 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
10e50 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
10e60 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
10e70 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
10e80 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
10e90 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
10ea0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
10eb0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
10ec0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
10ed0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10ee0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
10ef0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10f00 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
10f10 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
10f20 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
10f30 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
10f40 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
10f50 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
10f60 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
10f70 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
10f80 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
10f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10fa0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
10fb0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
10fc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
10fd0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
10fe0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
10ff0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
11000 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
11010 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
11020 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
11030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
11040 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
11050 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
11060 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
11070 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
11080 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
11090 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
110a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
110b0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
110c0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
110d0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
110e0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
110f0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
11100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
11110 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
11120 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
11130 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11140 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
11150 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
11160 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
11170 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
11180 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
11190 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
111a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
111b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
111c0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
111d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
111e0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
111f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
11200 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
11210 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
11220 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
11230 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
11240 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11250 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
11260 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
11270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
11280 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
11290 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
112a0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
112b0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
112c0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
112d0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
112e0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
112f0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
11300 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
11310 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
11320 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
11330 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
11340 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
11350 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
11360 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
11370 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
11380 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
11390 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
113a0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
113b0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
113c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
113d0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
113e0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
113f0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
11400 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
11410 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
11420 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
11430 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
11440 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
11450 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
11460 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
11470 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
11480 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
11490 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
114a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
114b0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
114c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
114d0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
114e0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
114f0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
11500 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
11510 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
11520 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
11530 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
11540 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
11550 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
11560 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
11570 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
11580 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
11590 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
115a0 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
115b0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
115c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
115d0 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
115e0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
115f0 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
11600 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
11610 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
11620 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
11630 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
11640 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
11650 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
11660 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
11670 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
11680 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
11690 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
116a0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
116b0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
116c0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
116d0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
116e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
116f0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
11700 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
11710 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
11720 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
11730 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
11740 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
11750 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
11760 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
11770 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
11780 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
11790 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
117a0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
117b0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
117c0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
117d0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
117e0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
117f0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
11800 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
11810 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
11820 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
11830 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
11840 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
11850 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
11860 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
11870 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
11880 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
11890 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
118a0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
118b0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
118c0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
118d0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
118e0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
118f0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
11900 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
11910 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
11920 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
11930 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
11940 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
11950 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
11960 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
11970 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11980 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
11990 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
119a0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
119b0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
119c0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
119d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
119e0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
119f0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11a00 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
11a10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
11a20 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
11a30 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
11a40 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
11a50 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
11a60 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
11a70 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
11a80 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
11a90 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11aa0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
11ab0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
11ac0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
11ad0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11ae0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
11af0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
11b00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11b10 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11b20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
11b30 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
11b40 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
11b50 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11b60 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11b70 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
11b80 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
11b90 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
11ba0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
11bb0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
11bc0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11bd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11be0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11c00 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
11c10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11c20 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
11c30 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
11c40 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
11c50 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
11c60 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
11c70 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
11c80 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
11c90 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
11ca0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
11cb0 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
11cc0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11cd0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11ce0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11cf0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11d00 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
11d10 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
11d20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
11d30 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
11d40 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
11d50 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
11d60 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
11d70 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
11d80 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
11d90 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
11da0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
11db0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
11dc0 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11dd0 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11de0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11df0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11e00 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
11e10 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
11e20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
11e30 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
11e40 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
11e50 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
11e60 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
11e70 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
11e80 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
11e90 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
11ea0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
11eb0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
11ec0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
11ed0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
11ee0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
11ef0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
11f00 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
11f10 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
11f20 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
11f30 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
11f40 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
11f50 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
11f60 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
11f70 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
11f80 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
11f90 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
11fa0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
11fb0 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
11fc0 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
11fd0 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
11fe0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
11ff0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
12000 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
12010 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
12020 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
12030 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
12040 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
12050 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
12060 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
12070 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
12080 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
12090 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
120a0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
120b0 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
120c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
120d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
120e0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
120f0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
12100 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
12110 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
12120 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
12130 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
12140 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
12150 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
12160 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
12170 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
12180 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
12190 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
121a0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
121b0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
121c0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
121d0 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
121e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
121f0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
12200 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
12210 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
12220 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
12230 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
12240 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
12250 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
12260 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
12270 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
12280 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
12290 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
122a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
122b0 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
122c0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
122d0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
122e0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
122f0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
12300 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
12310 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
12320 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
12330 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
12340 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
12350 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
12360 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
12370 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
12380 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
12390 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
123a0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
123b0 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
123c0 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
123d0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
123e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
123f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
12400 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12410 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12420 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12430 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
12440 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
12450 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
12460 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
12470 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
12480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12490 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
124a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
124b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
124c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
124d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
124e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
124f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
12500 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
12510 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
12520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
12530 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
12540 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
12550 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
12560 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12570 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
12580 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
12590 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
125a0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
125b0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
125c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
125d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
125e0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
125f0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
12600 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
12610 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
12620 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
12630 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
12640 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
12650 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
12660 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
12670 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
12680 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
12690 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
126a0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
126b0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
126c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
126d0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
126e0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
126f0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
12700 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
12710 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
12720 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
12730 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
12740 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
12750 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
12760 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
12770 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
12780 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
12790 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
127a0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
127b0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
127c0 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
127d0 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
127e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
127f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
12800 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
12810 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
12820 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
12830 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
12840 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
12850 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
12860 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
12870 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
12880 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
12890 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
128a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
128b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
128c0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
128d0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
128e0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
128f0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
12900 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
12910 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
12920 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
12930 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
12940 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
12950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12960 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
12970 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12980 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
12990 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
129a0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
129b0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
129c0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
129d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
129e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
129f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12a00 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
12a10 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
12a20 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
12a30 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
12a40 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
12a50 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
12a60 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
12a70 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
12a80 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
12a90 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
12aa0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
12ab0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
12ac0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
12ad0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
12ae0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
12af0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
12b00 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
12b10 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
12b20 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
12b30 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
12b40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
12b50 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12b60 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
12b70 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
12b80 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
12b90 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
12ba0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
12bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
12bc0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12bd0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12be0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12bf0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12c10 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
12c20 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
12c30 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
12c40 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
12c50 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
12c60 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
12c70 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
12c80 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
12c90 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
12ca0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12cb0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
12cc0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12cd0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12ce0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12cf0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12d00 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
12d10 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
12d20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
12d30 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
12d40 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
12d50 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
12d60 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
12d70 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
12d80 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
12d90 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
12da0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
12db0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
12dc0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12dd0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12de0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12df0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12e00 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
12e10 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
12e20 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12e30 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
12e40 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
12e50 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
12e60 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
12e70 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
12e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12e90 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
12ea0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
12eb0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
12ec0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
12ed0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12ee0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
12ef0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
12f00 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12f10 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
12f20 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
12f30 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
12f40 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
12f50 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
12f60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
12f70 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
12f80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12f90 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12fa0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
12fb0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
12fc0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
12fd0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
12fe0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
12ff0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
13000 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
13010 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
13020 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
13030 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
13040 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
13050 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
13060 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
13070 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
13080 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
13090 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
130a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
130b0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
130c0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
130d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
130e0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
130f0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
13100 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
13110 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
13120 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
13130 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
13140 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
13150 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
13160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13170 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
13180 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
13190 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
131a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
131b0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
131c0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
131d0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
131e0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
131f0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
13200 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
13210 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
13220 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
13230 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
13240 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
13250 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
13260 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
13270 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
13280 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
13290 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
132a0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
132b0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
132c0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
132d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
132e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
132f0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
13300 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
13310 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
13320 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
13330 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
13340 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
13350 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
13360 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
13370 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
13380 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
13390 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
133a0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
133b0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
133c0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
133d0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
133e0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
133f0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
13400 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
13410 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
13420 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
13430 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
13440 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
13450 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
13460 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
13470 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
13480 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
13490 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
134a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
134b0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
134c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
134d0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
134e0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
134f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
13500 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
13510 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
13520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
13530 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
13540 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
13550 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
13560 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
13570 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
13580 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
13590 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
135a0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
135b0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
135c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
135d0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
135e0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
135f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
13600 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
13610 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
13620 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
13630 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
13640 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
13650 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
13660 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
13670 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
13680 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
13690 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
136a0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
136b0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
136c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
136d0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
136e0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
136f0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13700 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
13710 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
13720 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
13730 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
13740 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
13750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
13760 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
13770 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13780 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
13790 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
137a0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
137b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
137c0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
137d0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
137e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
137f0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
13800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
13810 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
13820 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
13830 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
13840 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
13850 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
13860 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
13870 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
13880 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
13890 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
138a0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
138b0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
138c0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
138d0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
138e0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
138f0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
13900 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
13910 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
13920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13930 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
13940 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
13950 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
13960 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
13970 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
13980 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
13990 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
139a0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
139b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
139c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
139d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
139e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
139f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13a00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
13a10 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
13a20 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
13a30 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
13a40 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13a50 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
13a60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13a70 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
13a80 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
13a90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
13aa0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
13ab0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
13ac0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
13ad0 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
13ae0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13af0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
13b00 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
13b10 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
13b20 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
13b30 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
13b40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
13b50 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
13b60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13b70 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
13b80 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
13b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
13ba0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
13bb0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
13bc0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13be0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13bf0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13c00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
13c10 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
13c20 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
13c30 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
13c40 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
13c50 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
13c60 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
13c70 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
13c80 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
13c90 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
13ca0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13cb0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13cc0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13cd0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13ce0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13cf0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13d00 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
13d10 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
13d20 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
13d30 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
13d40 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
13d50 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
13d60 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
13d70 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
13d80 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
13d90 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
13da0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13db0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13dc0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13dd0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13de0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13df0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13e00 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
13e10 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
13e20 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
13e30 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
13e40 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13e50 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
13e60 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
13e70 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
13e80 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
13e90 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
13ea0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
13eb0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
13ec0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
13ed0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
13ee0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
13ef0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
13f00 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
13f10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
13f20 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
13f30 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
13f40 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
13f50 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
13f60 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
13f70 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
13f80 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
13f90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
13fa0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
13fb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
13fc0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
13fd0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
13fe0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
13ff0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
14000 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
14010 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
14020 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
14030 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
14040 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
14050 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
14060 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
14070 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
14080 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
14090 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
140a0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
140b0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
140c0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
140d0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
140e0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
140f0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
14100 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
14110 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
14120 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
14130 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
14140 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
14150 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
14160 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
14170 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
14180 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
14190 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
141a0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
141b0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
141c0 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
141d0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
141e0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
141f0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
14200 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
14210 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
14220 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
14230 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
14240 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
14250 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
14260 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
14270 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
14280 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
14290 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
142a0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
142b0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
142c0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
142d0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
142e0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
142f0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
14300 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
14310 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
14320 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
14330 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
14340 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
14350 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
14360 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
14370 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
14380 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14390 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
143a0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
143b0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
143c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
143d0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
143e0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
143f0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
14400 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
14410 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
14420 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
14430 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
14440 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
14450 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
14460 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
14470 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
14480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14490 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
144a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
144b0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
144c0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
144d0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
144e0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
144f0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
14500 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
14510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14520 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
14530 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
14540 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
14550 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
14560 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14570 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
14580 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
14590 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
145a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
145b0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
145c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
145d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
145e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
145f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
14600 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
14610 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
14620 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
14630 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
14640 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
14650 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
14660 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
14670 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
14680 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
14690 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
146a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
146b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
146c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
146d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
146e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
146f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
14700 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
14710 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
14720 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
14730 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
14740 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14750 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
14760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14770 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
14780 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
14790 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
147a0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
147b0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
147c0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
147d0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
147e0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
147f0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14810 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
14820 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
14830 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
14840 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
14850 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
14860 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14870 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
14880 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
14890 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
148a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
148b0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
148c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
148d0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
148e0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
148f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14900 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14910 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
14920 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
14930 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
14940 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
14950 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
14960 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14970 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
14980 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
14990 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
149a0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
149b0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
149c0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
149d0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
149e0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
149f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
14a00 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
14a10 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
14a20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
14a30 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
14a40 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
14a50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
14a60 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
14a70 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
14a80 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
14a90 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
14aa0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
14ab0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
14ac0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
14ad0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
14ae0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
14af0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
14b00 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
14b10 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
14b20 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
14b30 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
14b40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
14b50 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
14b60 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
14b70 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
14b80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14b90 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
14ba0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
14bb0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
14bc0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
14bd0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
14be0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
14bf0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
14c00 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
14c10 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
14c20 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
14c30 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
14c40 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
14c50 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
14c60 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
14c70 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
14c80 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
14c90 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
14ca0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
14cb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14cc0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
14cd0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
14ce0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
14d00 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
14d10 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
14d20 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
14d30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14d40 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
14d50 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
14d60 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
14d70 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
14d80 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
14d90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
14da0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
14db0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
14dc0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14dd0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
14de0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
14df0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
14e00 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
14e10 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
14e20 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
14e30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14e40 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
14e50 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14e60 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
14e70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14e80 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
14e90 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
14ea0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
14eb0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
14ec0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
14ed0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
14ee0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14ef0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
14f00 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
14f10 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
14f20 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
14f30 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
14f40 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
14f50 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
14f60 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
14f70 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
14f80 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
14f90 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
14fa0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
14fb0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
14fc0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14fd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14fe0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
14ff0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15000 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
15010 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
15020 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
15030 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
15040 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
15050 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
15060 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15070 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
15080 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15090 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
150a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
150b0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
150c0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
150d0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
150e0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
150f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
15100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
15110 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
15120 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
15130 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
15140 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
15150 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
15160 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
15170 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
15180 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
15190 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
151a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
151b0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
151c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
151d0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
151e0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
151f0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
15200 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
15210 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
15220 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
15230 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
15240 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
15250 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
15260 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
15270 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
15280 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
15290 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
152a0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
152b0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
152c0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
152d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
152e0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
152f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15300 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
15310 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
15320 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
15330 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15340 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
15350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
15360 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
15370 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
15380 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
15390 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
153a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
153b0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
153c0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
153d0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
153e0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
153f0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
15400 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
15410 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
15420 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
15430 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
15440 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
15450 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
15460 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
15470 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
15480 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
15490 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
154a0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
154b0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
154c0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
154d0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
154e0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
154f0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
15500 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
15510 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
15520 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
15530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
15540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
15550 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
15560 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
15570 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
15580 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
15590 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
155a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
155b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
155c0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
155d0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
155e0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
155f0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15600 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
15610 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
15620 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
15630 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
15640 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
15650 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
15660 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
15670 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
15680 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15690 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
156a0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
156b0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
156c0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
156d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
156e0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
156f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15700 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
15710 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
15720 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
15730 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
15740 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
15750 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
15760 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15770 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15780 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
157a0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
157b0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
157c0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
157d0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
157e0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
157f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
15800 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
15810 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
15820 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
15830 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
15840 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
15850 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
15860 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
15870 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15880 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
15890 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
158a0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
158b0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
158c0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
158d0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
158e0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
158f0 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f  ** ^(In sqlite3_
15900 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
15910 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
15920 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
15930 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
15940 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
15950 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
15960 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
15970 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
15980 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15990 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
159a0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
159b0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
159c0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
159d0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
159e0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
159f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
15a00 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
15a10 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
15a20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
15a30 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
15a40 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
15a50 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
15a60 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
15a70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
15a80 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
15a90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15aa0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
15ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
15ac0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
15ad0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
15ae0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
15af0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
15b00 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
15b10 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
15b20 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15b30 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
15b40 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
15b50 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
15b60 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
15b70 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
15b80 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
15b90 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
15ba0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
15bb0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
15bc0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
15bd0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
15be0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
15bf0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
15c00 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
15c10 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
15c20 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
15c30 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
15c40 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
15c50 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
15c60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
15c70 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
15c80 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
15c90 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
15ca0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
15cb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
15cc0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
15cd0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
15ce0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
15cf0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
15d00 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
15d10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15d20 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
15d30 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
15d40 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
15d50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15d60 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
15d70 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
15d80 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
15d90 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
15da0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
15db0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
15dc0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
15dd0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
15de0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
15df0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
15e00 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
15e10 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
15e20 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
15e30 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
15e40 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
15e50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
15e60 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
15e70 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
15e80 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
15e90 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
15ea0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
15eb0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
15ec0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
15ed0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
15ee0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
15ef0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
15f00 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
15f10 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
15f20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
15f30 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
15f40 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
15f50 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
15f60 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
15f70 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
15f80 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
15f90 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
15fa0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
15fb0 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
15fc0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
15fd0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15fe0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15ff0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
16000 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
16010 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
16020 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16030 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
16040 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
16050 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
16060 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
16070 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16080 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16090 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
160a0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
160b0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
160c0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
160d0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
160e0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
160f0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
16100 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
16110 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16120 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
16130 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
16140 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
16150 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
16160 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
16170 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
16180 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
16190 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
161a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
161b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
161c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
161d0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
161e0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
161f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16200 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
16210 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
16220 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
16230 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
16240 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
16250 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
16260 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
16270 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16280 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
16290 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
162a0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
162b0 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
162c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
162d0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
162e0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
162f0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
16300 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
16310 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
16320 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
16330 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
16340 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
16350 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
16360 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
16370 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
16380 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
16390 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
163a0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
163b0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
163c0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
163d0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
163e0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
163f0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
16400 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
16410 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
16420 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
16430 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
16440 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
16450 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
16460 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
16470 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
16480 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16490 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
164a0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
164b0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
164c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
164d0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
164e0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
164f0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
16500 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
16510 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
16520 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16530 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
16540 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
16550 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
16560 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
16570 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
16580 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
16590 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
165a0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
165b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
165c0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
165d0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
165e0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
165f0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
16600 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
16610 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
16620 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
16630 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
16640 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
16650 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
16660 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
16670 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
16680 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16690 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
166a0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
166b0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
166c0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
166d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
166e0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
166f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
16700 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
16710 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
16720 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16730 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
16740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
16750 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
16760 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
16770 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
16780 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
16790 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
167a0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
167b0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
167c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
167d0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
167e0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
167f0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
16800 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
16810 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
16820 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
16830 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
16840 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
16850 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
16860 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
16870 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
16880 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16890 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
168a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
168b0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
168c0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
168d0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
168e0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
168f0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
16900 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
16910 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
16920 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
16930 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
16940 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
16950 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
16960 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
16970 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
16980 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
16990 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
169a0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
169b0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
169c0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
169d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
169e0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
169f0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
16a00 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
16a10 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
16a20 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
16a30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16a40 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
16a50 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
16a60 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
16a70 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
16a80 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
16a90 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
16aa0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
16ab0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
16ac0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
16ad0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
16ae0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
16af0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
16b00 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
16b10 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
16b20 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
16b30 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
16b40 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
16b50 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
16b60 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
16b70 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
16b80 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
16b90 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
16ba0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
16bb0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
16bc0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
16bd0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
16be0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
16bf0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
16c00 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
16c10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
16c20 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
16c30 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
16c40 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
16c50 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16c60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
16c70 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
16c80 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
16c90 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
16ca0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
16cb0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
16cc0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
16cd0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
16ce0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
16cf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16d00 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
16d10 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
16d20 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
16d30 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
16d40 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
16d50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16d60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16d70 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
16d80 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
16d90 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
16da0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
16db0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
16dc0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
16dd0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16de0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16df0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
16e00 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
16e10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
16e20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
16e30 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
16e40 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
16e50 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
16e60 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
16e70 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
16e80 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
16e90 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
16ea0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
16eb0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
16ec0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
16ed0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
16ee0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
16ef0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
16f00 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
16f10 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
16f20 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
16f30 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
16f40 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
16f50 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
16f60 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
16f70 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
16f80 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
16f90 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
16fa0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
16fb0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
16fc0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
16fd0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
16fe0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
16ff0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
17000 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
17010 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
17020 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
17030 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
17040 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
17050 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
17060 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
17070 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
17080 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
17090 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
170a0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
170b0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
170c0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
170d0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
170e0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
170f0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
17100 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
17110 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
17120 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
17130 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
17140 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
17150 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
17160 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
17170 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
17180 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
17190 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
171a0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
171b0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
171c0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
171d0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
171e0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
171f0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
17200 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
17210 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
17220 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
17230 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
17240 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
17250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
17260 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
17270 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
17280 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
17290 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
172a0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
172b0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
172c0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
172d0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
172e0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
172f0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
17300 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
17310 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
17320 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
17330 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
17340 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
17350 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
17360 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
17370 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
17380 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
17390 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
173a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
173b0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
173c0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
173d0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
173e0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
173f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
17400 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
17410 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
17420 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
17430 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
17440 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
17450 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
17460 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
17470 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
17480 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
17490 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
174a0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
174b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
174c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
174d0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
174e0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
174f0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
17500 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
17510 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
17520 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
17530 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
17540 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
17550 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
17560 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
17570 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
17580 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
17590 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
175a0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
175b0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
175c0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
175d0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
175e0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
175f0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
17600 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
17610 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
17620 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
17630 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
17640 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
17650 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
17660 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
17670 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
17680 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
17690 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
176a0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
176b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
176c0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
176d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
176e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
176f0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
17700 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
17710 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
17720 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
17730 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
17740 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
17750 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
17760 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
17770 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
17780 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
17790 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
177a0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
177b0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
177c0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
177d0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
177e0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
177f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
17800 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
17810 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
17820 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
17830 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
17840 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
17850 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
17860 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
17870 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
17880 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
17890 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
178a0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
178b0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
178c0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
178d0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
178e0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
178f0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
17900 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
17910 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
17920 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
17930 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
17940 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
17950 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
17960 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
17970 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
17980 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17990 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
179a0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
179b0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
179c0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
179d0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
179e0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
179f0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
17a00 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
17a10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
17a20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
17a30 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
17a40 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
17a50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
17a60 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
17a70 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
17a80 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
17a90 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
17aa0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
17ab0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
17ac0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
17ad0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
17ae0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
17af0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
17b00 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
17b10 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
17b20 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
17b30 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
17b40 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
17b50 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
17b60 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
17b70 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
17b80 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
17b90 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
17ba0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
17bb0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
17bc0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
17bd0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
17be0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
17bf0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
17c00 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
17c10 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
17c20 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
17c30 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
17c40 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
17c50 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
17c60 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
17c70 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
17c80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
17c90 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
17ca0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
17cb0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
17cc0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
17cd0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
17ce0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
17cf0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
17d00 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
17d10 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
17d20 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
17d30 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
17d40 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
17d50 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
17d60 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
17d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
17d80 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
17d90 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
17da0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
17db0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
17dc0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
17dd0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
17de0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
17df0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
17e00 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
17e10 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
17e20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
17e30 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
17e40 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17e50 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
17e60 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
17e70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
17e80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17e90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
17ea0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
17eb0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
17ec0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
17ed0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
17ee0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
17ef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17f00 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
17f10 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
17f20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
17f30 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
17f40 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
17f50 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
17f60 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
17f70 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
17f80 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
17f90 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
17fa0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
17fb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17fc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
17fd0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
17fe0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
17ff0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
18000 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18010 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
18020 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
18030 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
18040 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
18050 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
18060 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
18070 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
18080 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
18090 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
180a0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
180b0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
180c0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
180d0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
180e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
180f0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
18100 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
18110 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18120 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
18130 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
18140 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
18150 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
18160 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
18170 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
18180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18190 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
181a0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
181b0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
181c0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
181d0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
181e0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
181f0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
18200 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
18210 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
18220 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
18230 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
18240 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
18250 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18260 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
18270 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18280 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
18290 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
182a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
182b0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
182c0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
182d0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
182e0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
182f0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
18300 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
18310 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
18320 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
18330 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18340 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
18350 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
18360 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
18370 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18380 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
18390 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
183a0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
183b0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
183c0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
183d0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
183e0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
183f0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
18400 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
18410 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
18420 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
18430 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
18440 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
18450 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
18460 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
18470 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
18480 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
18490 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
184a0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
184b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^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 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
184e0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
184f0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18500 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
18510 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
18520 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
18530 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
18540 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
18550 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
18560 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
18570 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
18580 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
18590 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
185a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
185b0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
185c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
185d0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
185e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
185f0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
18600 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
18610 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
18620 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
18630 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
18640 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
18650 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
18660 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18670 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
18680 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
18690 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
186a0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
186b0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
186c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
186d0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
186e0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
186f0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
18700 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
18710 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
18720 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
18730 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
18740 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18750 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
18760 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
18770 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
18780 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
18790 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
187a0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
187b0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
187c0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
187d0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
187e0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
187f0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
18800 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
18810 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
18820 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
18830 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
18840 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
18850 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
18860 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
18870 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
18880 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
18890 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
188a0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
188b0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
188c0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
188d0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
188e0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
188f0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
18900 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
18910 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
18920 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
18930 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
18940 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
18950 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
18960 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
18970 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
18980 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
18990 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
189a0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
189b0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
189c0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
189d0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
189e0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
189f0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
18a00 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
18a10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
18a20 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
18a30 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
18a40 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
18a50 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
18a60 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
18a70 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
18a80 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
18a90 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
18aa0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
18ab0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
18ac0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
18ad0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
18ae0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
18af0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
18b00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
18b10 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
18b20 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
18b30 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
18b40 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
18b50 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
18b60 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
18b70 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
18b80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
18b90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
18ba0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18bb0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
18bc0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
18bd0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
18be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18bf0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18c00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18c10 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
18c20 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
18c30 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
18c40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18c50 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
18c60 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
18c70 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
18c80 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
18c90 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
18ca0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
18cb0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
18cc0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
18cd0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
18ce0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
18cf0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
18d00 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
18d10 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
18d20 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
18d30 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
18d40 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
18d50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
18d60 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
18d70 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
18d80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18d90 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
18da0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
18db0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
18dd0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
18de0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
18df0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
18e00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
18e10 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
18e20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
18e30 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
18e40 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
18e50 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
18e60 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
18e70 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
18e80 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
18e90 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
18ea0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
18eb0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
18ec0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
18ed0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
18ee0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
18ef0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
18f00 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
18f10 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
18f20 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
18f30 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
18f40 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
18f50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
18f60 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
18f70 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
18f80 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
18f90 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
18fa0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
18fb0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
18fc0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
18fd0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18fe0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
18ff0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19000 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
19010 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
19020 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
19030 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
19040 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
19050 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
19060 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
19070 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
19080 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
19090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
190a0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
190b0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
190c0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
190d0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
190e0 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
190f0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
19100 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
19110 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
19120 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
19130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
19140 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
19150 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
19160 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
19170 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
19180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19190 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
191a0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
191b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
191c0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
191d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
191e0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
191f0 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
19200 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
19210 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
19220 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
19230 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
19240 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
19250 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
19260 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
19270 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
19280 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
19290 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
192a0 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
192b0 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
192c0 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
192d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
192e0 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
192f0 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
19300 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
19310 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
19320 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
19330 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
19340 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
19350 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
19360 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
19370 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
19380 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19390 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
193a0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
193b0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
193c0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
193d0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
193e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
193f0 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
19400 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
19410 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
19420 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
19430 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
19440 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
19450 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
19460 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
19470 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
19480 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
19490 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
194a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
194b0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
194c0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
194d0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
194e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
194f0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
19500 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
19510 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
19520 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
19530 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
19540 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
19550 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19560 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19570 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
19580 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
19590 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
195a0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
195b0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
195c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
195d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
195e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
195f0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
19600 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
19610 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19620 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19640 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
19650 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
19660 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19670 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19690 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
196a0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
196b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
196c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
196d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
196e0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
196f0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
19700 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19710 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19730 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
19740 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
19750 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
19760 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19780 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
19790 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
197a0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
197b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
197c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
197d0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
197e0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
197f0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
19800 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19810 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
19820 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
19830 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
19840 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19850 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19860 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
19870 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
19880 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
19890 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
198a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
198b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
198c0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
198d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
198e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
198f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19900 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
19910 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
19920 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19930 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19940 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19950 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
19960 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
19970 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19980 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19990 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
199a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
199b0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
199c0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
199d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
199e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
199f0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
19a00 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
19a10 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
19a20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19a30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19a40 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
19a50 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
19a60 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19a70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19a80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19a90 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
19aa0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
19ab0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19ac0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19ad0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19ae0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
19af0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
19b00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19b10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19b20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19b30 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
19b40 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
19b50 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
19b60 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
19b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19b80 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
19b90 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
19ba0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
19bb0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
19bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19bd0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
19be0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
19bf0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
19c00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19c10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
19c20 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
19c30 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
19c40 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
19c50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
19c70 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
19c80 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
19c90 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
19ca0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
19cc0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
19cd0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
19ce0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
19cf0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19d00 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
19d10 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
19d20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
19d30 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
19d40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19d50 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
19d60 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
19d70 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
19d80 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
19d90 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19da0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
19db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
19dc0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
19dd0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19de0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19df0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
19e00 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
19e10 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19e20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19e30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19e40 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
19e50 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
19e60 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19e70 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
19e80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19e90 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
19ea0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
19eb0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19ec0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
19ed0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19ee0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
19ef0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
19f00 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
19f10 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
19f20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19f30 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
19f40 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
19f50 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
19f60 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
19f70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19f80 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
19f90 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
19fa0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
19fb0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
19fc0 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
19fd0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
19fe0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
19ff0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1a000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a010 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1a020 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1a030 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1a040 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1a050 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a060 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1a070 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1a080 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1a090 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1a0a0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1a0b0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1a0c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1a0d0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1a0e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1a0f0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1a100 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1a110 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1a120 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1a130 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1a140 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1a150 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1a160 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1a170 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1a180 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1a190 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1a1a0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1a1b0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1a1c0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1a1d0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1a1e0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1a1f0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1a200 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1a210 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1a220 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1a230 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1a240 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1a250 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1a260 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1a270 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1a280 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1a290 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1a2a0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1a2b0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1a2c0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1a2d0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1a2e0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1a2f0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1a300 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1a310 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1a320 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1a330 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1a340 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1a350 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1a360 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1a370 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1a380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1a390 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1a3a0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1a3b0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1a3c0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1a3d0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1a3e0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1a3f0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1a400 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1a410 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1a420 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1a430 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1a440 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1a450 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1a460 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1a470 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1a480 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1a490 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1a4a0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1a4b0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1a4c0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1a4d0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1a4e0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1a4f0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1a500 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1a510 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1a520 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1a530 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1a540 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1a550 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1a560 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1a570 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1a580 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1a590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a5a0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1a5b0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1a5c0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1a5d0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1a5e0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1a5f0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1a600 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1a610 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1a620 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1a630 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1a640 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1a650 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1a660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a670 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1a680 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1a690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a6a0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1a6b0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1a6c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1a6d0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1a6e0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1a6f0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1a700 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1a710 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1a720 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1a730 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1a740 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1a750 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1a760 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1a770 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1a780 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1a790 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1a7a0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1a7b0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1a7c0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1a7d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1a7e0 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1a7f0 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1a800 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1a810 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1a820 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1a830 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1a840 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1a850 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1a860 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1a870 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1a880 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1a890 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1a8a0 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1a8b0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1a8c0 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1a8d0 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1a8e0 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1a8f0 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1a900 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1a910 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1a920 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1a930 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1a940 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1a950 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1a960 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1a970 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1a980 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1a990 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1a9a0 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1a9b0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1a9c0 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1a9d0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1a9e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1a9f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1aa00 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1aa10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aa20 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1aa30 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1aa40 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1aa50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1aa60 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1aa70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1aa80 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1aa90 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1aaa0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1aab0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1aac0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1aad0 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1aae0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1aaf0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1ab00 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1ab10 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1ab20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ab30 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1ab40 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1ab50 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1ab60 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1ab70 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1ab80 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
1ab90 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
1aba0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1abb0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1abc0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1abd0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1abe0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1abf0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ac00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ac10 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1ac20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ac30 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1ac40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ac50 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1ac60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ac70 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1ac80 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1ac90 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1aca0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1acb0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1acc0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1acd0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1ace0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1acf0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1ad00 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1ad10 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1ad20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1ad30 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1ad40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1ad50 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1ad60 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1ad70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ad80 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1ad90 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1ada0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1adb0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1adc0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1add0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1ade0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1adf0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1ae00 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1ae10 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1ae20 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1ae30 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1ae40 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1ae50 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1ae60 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1ae70 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1ae80 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1ae90 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1aea0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1aeb0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1aec0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1aed0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1aee0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1aef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1af00 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1af10 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1af20 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1af30 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1af40 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1af50 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1af60 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1af70 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1af80 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1af90 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1afa0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1afb0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1afc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1afd0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1afe0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1aff0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1b000 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1b010 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1b020 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1b030 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b040 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1b050 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1b060 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1b070 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1b080 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1b090 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1b0a0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1b0b0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1b0c0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1b0d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1b0e0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1b0f0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1b100 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1b110 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1b120 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1b130 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1b140 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1b150 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1b160 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b170 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1b180 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1b190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1b1a0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64  EDCACHE],.** and
1b1b0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1b1c0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1b1d0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1b1e0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1b1f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1b200 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1b210 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b220 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1b230 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1b240 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1b250 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1b260 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1b270 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1b280 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1b290 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1b2a0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1b2b0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1b2c0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1b2d0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1b2e0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1b2f0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1b300 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1b310 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1b320 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1b330 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1b340 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1b350 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1b360 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1b370 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1b380 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1b390 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b3a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1b3b0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1b3c0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1b3d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1b3e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1b3f0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1b400 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1b410 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a  s creates it if.
1b420 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1b430 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1b440 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1b450 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1b460 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1b470 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1b480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1b490 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1b4a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1b4b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1b4c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b4d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1b4e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1b4f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1b500 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1b510 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1b520 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1b530 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1b540 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b550 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1b560 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20  _FULLMUTEX],.** 
1b570 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1b580 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72  REDCACHE] and/or
1b590 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1b5a0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1b5b0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s,.** then the b
1b5c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1b5d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1b5e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1b5f0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1b600 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1b610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b620 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1b630 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1b640 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1b650 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1b660 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1b670 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1b680 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1b690 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1b6a0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1b6b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1b6c0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1b6d0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1b6e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b6f0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1b700 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1b710 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1b720 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1b730 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1b740 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1b750 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1b760 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1b770 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1b780 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1b790 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1b7a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b7b0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1b7c0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1b7d0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1b7e0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1b7f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1b800 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1b810 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1b820 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1b830 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1b840 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1b850 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1b860 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1b870 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1b880 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1b890 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1b8a0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1b8b0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1b8c0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1b8d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1b8e0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1b8f0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1b900 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1b910 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1b920 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1b930 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1b940 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1b950 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1b960 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1b970 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b980 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1b990 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1b9a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1b9b0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1b9c0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1b9d0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1b9e0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1b9f0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1ba00 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1ba10 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1ba20 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1ba30 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1ba40 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1ba50 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1ba60 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1ba70 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1ba80 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1ba90 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1baa0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1bab0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1bac0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1bad0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1bae0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1baf0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1bb00 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1bb10 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1bb20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1bb30 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1bb40 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1bb50 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1bb60 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1bb70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1bb80 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  losed..**.** ^Th
1bb90 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1bba0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1bbb0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1bbc0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1bbd0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1bbe0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1bbf0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1bc00 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1bc10 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1bc20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bc30 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1bc40 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1bc50 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1bc60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1bc70 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1bc80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1bc90 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1bca0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1bcb0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1bcc0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1bcd0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1bce0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1bcf0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1bd00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1bd10 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1bd20 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1bd30 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1bd40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1bd50 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1bd60 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1bd70 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1bd80 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1bd90 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1bda0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1bdb0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1bdc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1bdd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1bde0 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  _v2()..*/.int sq
1bdf0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1be00 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1be10 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1be20 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1be30 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1be40 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1be50 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1be60 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1be70 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1be80 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1be90 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1bea0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1beb0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1bec0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1bed0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1bee0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1bef0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1bf00 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1bf10 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1bf20 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1bf30 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1bf40 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1bf50 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1bf60 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1bf70 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1bf80 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1bf90 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1bfa0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1bfb0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1bfc0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1bfd0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1bfe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bff0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1c000 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
1c010 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1c020 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1c030 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1c040 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1c050 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1c060 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1c070 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1c080 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1c090 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1c0a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1c0b0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1c0c0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1c0d0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1c0e0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1c0f0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1c100 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1c110 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1c120 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1c130 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1c140 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
1c150 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1c160 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
1c170 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
1c180 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
1c190 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1c1a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
1c1b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
1c1c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
1c1d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
1c1e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
1c1f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c200 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1c210 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1c220 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1c230 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1c240 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1c250 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1c260 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1c270 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1c280 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
1c290 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1c2a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1c2b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1c2c0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1c2d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1c2e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1c2f0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1c300 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1c310 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1c320 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1c330 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1c340 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1c350 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1c360 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1c370 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1c380 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
1c390 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1c3a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1c3b0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1c3c0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1c3d0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1c3e0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1c3f0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1c400 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1c410 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1c420 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1c430 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1c440 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1c450 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1c460 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1c470 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1c480 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1c490 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1c4a0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1c4b0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1c4c0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1c4d0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1c4e0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1c4f0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1c500 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1c510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c520 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1c530 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1c540 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1c550 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1c560 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1c570 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1c580 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1c590 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1c5a0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1c5b0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1c5c0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1c5d0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1c5e0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1c5f0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1c600 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1c610 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1c620 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1c630 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1c640 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1c650 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1c660 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1c670 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1c680 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1c690 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1c6a0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1c6b0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
1c6c0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1c6d0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1c6e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1c6f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1c700 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1c710 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1c720 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1c730 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1c740 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1c750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c760 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1c770 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1c780 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
1c790 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
1c7a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
1c7b0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1c7c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
1c7d0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
1c7e0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
1c7f0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
1c800 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
1c810 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
1c820 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
1c830 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
1c840 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
1c850 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
1c860 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
1c870 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
1c880 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
1c890 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
1c8a0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1c8b0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
1c8c0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
1c8d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1c8e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1c8f0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
1c900 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
1c910 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
1c920 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
1c930 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
1c940 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1c950 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
1c960 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
1c970 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
1c980 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1c990 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
1c9a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1c9b0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
1c9c0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1c9d0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
1c9e0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
1c9f0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
1ca00 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
1ca10 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1ca20 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
1ca30 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1ca40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
1ca50 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1ca60 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
1ca70 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
1ca80 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
1ca90 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
1caa0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1cab0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1cac0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
1cad0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
1cae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1caf0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
1cb00 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
1cb10 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1cb20 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1cb30 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1cb40 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1cb50 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1cb60 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1cb70 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1cb80 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1cb90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1cba0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1cbb0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1cbc0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1cbd0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1cbe0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1cbf0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1cc00 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1cc10 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1cc20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1cc30 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1cc40 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1cc50 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1cc60 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1cc70 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
1cc80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1cc90 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1cca0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1ccb0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1ccc0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
1ccd0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
1cce0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
1ccf0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
1cd00 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1cd10 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1cd20 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
1cd30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
1cd40 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1cd50 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
1cd60 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1cd70 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
1cd80 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1cd90 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1cda0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1cdb0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1cdc0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1cdd0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1cde0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1cdf0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1ce00 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1ce10 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1ce20 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1ce30 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
1ce40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1ce50 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
1ce60 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
1ce70 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
1ce80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1ce90 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
1cea0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
1ceb0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
1cec0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
1ced0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
1cee0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
1cef0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
1cf00 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
1cf10 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
1cf20 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
1cf30 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
1cf40 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1cf50 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1cf60 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1cf70 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1cf80 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1cf90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1cfa0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1cfb0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1cfc0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1cfd0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1cfe0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1cff0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1d000 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1d010 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1d020 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1d030 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1d040 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1d050 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1d060 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1d070 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1d080 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1d090 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1d0a0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1d0b0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1d0c0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1d0d0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1d0e0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1d0f0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1d100 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1d110 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1d120 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1d130 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1d140 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1d150 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1d160 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1d170 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1d180 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1d190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1d1a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1d1b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1d1c0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1d1d0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1d1e0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1d1f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1d200 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1d210 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1d220 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1d230 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1d240 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1d250 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1d260 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1d270 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1d280 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1d290 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1d2a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1d2b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1d2c0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1d2d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1d2e0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1d2f0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1d300 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1d310 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1d320 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1d330 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1d340 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1d350 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1d360 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1d370 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1d380 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1d390 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1d3a0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1d3b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1d3c0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1d3d0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1d3e0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1d3f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1d400 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1d410 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1d420 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1d430 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1d440 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1d450 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d460 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1d470 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1d480 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1d490 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
1d4a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d4b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1d4c0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1d4d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d4e0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1d4f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1d500 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1d510 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1d520 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1d530 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d540 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1d550 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1d560 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1d570 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1d580 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1d590 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1d5a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1d5b0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1d5c0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1d5d0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1d5e0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1d5f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1d600 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1d610 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1d620 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1d630 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1d640 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1d650 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1d660 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d670 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1d680 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1d690 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1d6a0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1d6b0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1d6c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1d6d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d6e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1d6f0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1d700 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1d710 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1d720 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1d730 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1d740 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1d750 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1d760 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
1d770 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
1d780 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
1d790 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
1d7a0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
1d7b0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
1d7c0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
1d7d0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
1d7e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d7f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1d800 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d810 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1d820 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1d830 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1d840 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1d850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1d860 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1d870 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d880 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1d890 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1d8a0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1d8b0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1d8c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1d8d0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1d8e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d8f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1d900 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1d910 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1d920 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1d930 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1d940 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d950 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1d960 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1d970 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
1d980 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
1d990 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
1d9a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1d9b0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  nt.)^.**.** ^(<d
1d9c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
1d9d0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
1d9e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d9f0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
1da00 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
1da10 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
1da20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
1da30 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
1da40 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1da50 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
1da60 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
1da70 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
1da80 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
1da90 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1daa0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
1dab0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
1dac0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1dad0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
1dae0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
1daf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1db00 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1db10 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
1db20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1db30 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
1db40 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
1db50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1db60 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1db70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
1db80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1db90 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
1dba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
1dbb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dbc0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1dbd0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
1dbe0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
1dbf0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1dc00 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
1dc10 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
1dc20 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
1dc30 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1dc40 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
1dc50 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
1dc60 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
1dc70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1dc80 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1dc90 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
1dca0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
1dcb0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
1dcc0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
1dcd0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
1dce0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
1dcf0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
1dd00 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
1dd10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1dd20 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
1dd30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dd40 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
1dd50 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
1dd60 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1dd70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1dd80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1dd90 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
1dda0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
1ddb0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
1ddc0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
1ddd0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
1dde0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
1ddf0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
1de00 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
1de10 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
1de20 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
1de30 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
1de40 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
1de50 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1de60 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
1de70 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
1de80 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
1de90 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
1dea0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
1deb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1dec0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
1ded0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
1dee0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
1def0 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
1df00 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
1df10 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
1df20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
1df30 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
1df40 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1df50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1df60 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1df70 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1df80 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1df90 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
1dfa0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1dfb0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1dfc0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1dfd0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1dfe0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1dff0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1e000 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1e010 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1e020 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1e030 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1e040 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1e050 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1e060 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1e070 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1e080 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1e090 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1e0a0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1e0b0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1e0c0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1e0d0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1e0e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1e0f0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1e100 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1e110 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1e120 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1e130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
1e140 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
1e150 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
1e160 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1e170 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
1e180 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
1e190 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
1e1a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1e1b0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1e1c0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
1e1d0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
1e1e0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1e1f0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1e200 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
1e210 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
1e220 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1e230 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
1e240 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
1e250 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
1e260 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1e270 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
1e280 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
1e290 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
1e2a0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
1e2b0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
1e2c0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
1e2d0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
1e2e0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1e2f0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1e300 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1e310 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1e320 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1e330 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1e340 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
1e350 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1e360 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1e370 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1e380 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1e390 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1e3a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1e3b0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1e3c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1e3d0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
1e3e0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
1e3f0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
1e400 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1e410 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
1e420 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1e430 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
1e440 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1e450 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1e460 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1e470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e480 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
1e490 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
1e4a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
1e4b0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
1e4c0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
1e4d0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
1e4e0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
1e4f0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
1e500 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1e510 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
1e520 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
1e530 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
1e540 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1e550 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1e560 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1e570 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1e580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1e590 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1e5a0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1e5b0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
1e5c0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
1e5d0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1e5e0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1e5f0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1e600 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
1e610 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
1e620 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1e630 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
1e640 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
1e650 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
1e660 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
1e670 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
1e680 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
1e690 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
1e6a0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
1e6b0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1e6c0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
1e6d0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
1e6e0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
1e6f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1e700 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1e710 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1e720 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1e730 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1e740 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1e750 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1e760 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1e770 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1e780 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1e790 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1e7a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1e7b0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1e7c0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1e7d0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1e7e0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1e7f0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1e800 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1e810 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1e820 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e830 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1e840 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1e850 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1e860 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1e870 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1e880 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1e890 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1e8a0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1e8b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1e8c0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1e8d0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1e8e0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
1e8f0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
1e900 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
1e910 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
1e920 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
1e930 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
1e940 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
1e950 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
1e960 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1e970 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
1e980 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
1e990 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1e9a0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
1e9b0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
1e9c0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
1e9d0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
1e9e0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
1e9f0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
1ea00 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
1ea10 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1ea20 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
1ea30 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
1ea40 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
1ea50 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
1ea60 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
1ea70 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
1ea80 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
1ea90 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
1eaa0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
1eab0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
1eac0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
1ead0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
1eae0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
1eaf0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
1eb00 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
1eb10 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
1eb20 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
1eb30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
1eb40 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69  BLE_STAT2] compi
1eb50 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
1eb60 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
1eb70 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
1eb80 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
1eb90 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
1eba0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1ebb0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1ebc0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1ebd0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1ebe0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1ebf0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1ec00 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1ec10 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1ec20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1ec30 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1ec40 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1ec50 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1ec60 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1ec70 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1ec80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1ec90 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1eca0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1ecb0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1ecc0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1ecd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ece0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1ecf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1ed00 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1ed10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1ed20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1ed30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1ed40 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1ed50 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1ed60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1ed70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1ed80 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1ed90 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1eda0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1edb0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1edc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1edd0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1ede0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1edf0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1ee00 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1ee10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1ee20 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
1ee30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1ee40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1ee50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1ee60 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1ee70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1ee80 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1ee90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1eea0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1eeb0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1eec0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1eed0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1eee0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1eef0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1ef00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1ef10 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1ef20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1ef30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1ef40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1ef50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1ef60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1ef70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1ef80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1ef90 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1efa0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1efb0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1efc0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1efd0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1efe0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1eff0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1f000 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1f010 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1f020 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1f030 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1f040 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1f050 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1f060 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1f070 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1f080 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1f090 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1f0a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f0b0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1f0c0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
1f0d0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
1f0e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
1f0f0 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
1f100 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
1f110 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
1f120 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
1f130 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1f140 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
1f150 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
1f160 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1f170 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1f180 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1f190 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f1a0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
1f1b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1f1c0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
1f1d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1f1e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1f1f0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1f200 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
1f210 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
1f220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f230 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
1f240 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1f250 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
1f260 72 6f 29 20 69 66 20 0a 2a 2a 20 61 6e 64 20 6f  ro) if .** and o
1f270 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
1f280 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f290 58 20 69 73 20 6d 61 6b 65 73 20 6e 6f 20 64 69  X is makes no di
1f2a0 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
1f2b0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
1f2c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1f2d0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
1f2e0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
1f2f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1f300 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
1f310 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
1f320 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
1f330 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
1f340 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
1f350 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
1f360 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
1f370 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
1f380 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
1f390 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
1f3a0 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
1f3b0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
1f3c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
1f3d0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
1f3e0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
1f3f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
1f400 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
1f410 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1f420 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1f430 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
1f440 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
1f450 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
1f460 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1f470 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
1f480 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
1f490 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
1f4a0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
1f4b0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
1f4c0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
1f4d0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
1f4e0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
1f4f0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
1f500 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
1f510 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
1f520 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
1f530 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
1f540 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
1f550 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
1f560 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
1f570 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
1f580 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
1f590 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
1f5a0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
1f5b0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
1f5c0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
1f5d0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
1f5e0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
1f5f0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
1f600 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
1f610 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
1f620 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
1f630 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
1f640 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
1f650 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
1f660 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
1f670 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
1f680 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
1f690 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
1f6a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
1f6b0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
1f6c0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
1f6d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f6e0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
1f6f0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
1f700 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
1f710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1f720 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
1f730 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
1f740 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
1f750 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1f760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f770 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1f780 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
1f790 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1f7a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1f7b0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1f7c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1f7d0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1f7e0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1f7f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1f800 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1f810 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1f820 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1f830 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1f840 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1f850 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
1f860 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1f870 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
1f880 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1f890 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f8a0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1f8b0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1f8c0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1f8d0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1f8e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1f8f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1f900 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1f910 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1f920 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1f930 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1f940 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1f950 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1f960 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1f970 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1f980 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1f990 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1f9a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1f9b0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1f9c0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1f9d0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1f9e0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1f9f0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1fa00 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1fa10 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1fa20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1fa30 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1fa40 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1fa50 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1fa60 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1fa70 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1fa80 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1fa90 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1faa0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1fab0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1fac0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fad0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1fae0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1faf0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1fb00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fb10 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1fb20 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1fb30 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1fb40 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1fb50 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1fb60 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1fb70 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1fb80 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1fb90 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1fba0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1fbb0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1fbc0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1fbd0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1fbe0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1fbf0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1fc00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1fc10 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1fc20 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1fc30 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1fc40 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1fc50 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1fc60 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1fc70 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1fc80 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1fc90 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1fca0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1fcb0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1fcc0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1fcd0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1fce0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1fcf0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1fd00 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1fd10 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1fd20 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
1fd30 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
1fd40 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1fd50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
1fd60 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1fd70 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1fd80 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1fd90 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1fda0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1fdb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1fdc0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1fdd0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
1fde0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1fdf0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1fe00 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
1fe10 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
1fe20 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
1fe30 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
1fe40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fe50 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
1fe60 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
1fe70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1fe80 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
1fe90 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
1fea0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
1feb0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
1fec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
1fed0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
1fee0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
1fef0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
1ff00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ff10 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
1ff20 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
1ff30 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
1ff40 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1ff50 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
1ff60 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
1ff70 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1ff80 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1ff90 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1ffa0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1ffb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1ffc0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
1ffd0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1ffe0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
1fff0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
20000 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
20010 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
20020 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
20030 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
20040 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20050 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
20060 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
20070 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
20080 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
20090 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
200a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
200b0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
200c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
200d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
200e0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
200f0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
20100 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
20110 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
20120 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
20130 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
20140 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
20150 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
20160 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
20170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
20180 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
20190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
201a0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
201b0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
201c0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
201d0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
201e0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
201f0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
20200 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
20210 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
20220 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
20230 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
20240 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
20250 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
20260 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20270 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
20280 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20290 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
202a0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
202b0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
202c0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
202d0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
202e0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
202f0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
20300 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
20310 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
20320 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
20330 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
20340 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
20350 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
20360 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
20370 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
20380 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
20390 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
203a0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
203b0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
203c0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
203d0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
203e0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
203f0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
20400 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
20410 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
20420 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
20430 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
20440 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
20450 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
20460 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
20470 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
20480 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
20490 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
204a0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
204b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
204c0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
204d0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
204e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
204f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
20500 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
20510 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
20520 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
20530 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
20540 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
20550 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
20560 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
20570 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
20580 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
20590 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
205a0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
205b0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
205c0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
205d0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
205e0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
205f0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
20600 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
20610 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
20620 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
20630 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
20640 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
20650 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20660 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20670 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
20680 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
20690 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
206a0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
206b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
206c0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
206d0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
206e0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
206f0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
20700 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
20710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
20720 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
20730 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
20740 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
20750 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
20760 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
20770 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
20780 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
20790 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
207a0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
207b0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
207c0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
207d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
207e0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
207f0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
20800 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
20810 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
20820 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
20830 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
20840 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
20850 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
20860 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20870 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
20880 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
20890 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
208a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
208b0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
208c0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
208d0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tor..**.** ^The 
208e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
208f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
20900 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
20910 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
20920 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
20930 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
20940 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
20950 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
20960 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
20970 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
20980 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
20990 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
209a0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
209b0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
209c0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
209d0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
209e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
209f0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
20a00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20a10 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
20a20 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
20a30 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
20a40 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
20a50 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
20a60 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
20a70 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
20a80 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
20a90 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
20aa0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
20ab0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
20ac0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
20ad0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
20ae0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
20af0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
20b00 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
20b10 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
20b20 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
20b30 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
20b40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
20b50 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
20b60 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
20b70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
20b80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20b90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20ba0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
20bb0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
20bc0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
20bd0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
20be0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
20bf0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
20c00 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
20c10 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
20c20 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
20c30 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
20c40 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
20c50 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
20c60 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
20c70 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
20c80 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
20c90 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
20ca0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
20cb0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
20cc0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
20cd0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
20ce0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
20cf0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
20d00 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
20d10 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
20d20 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
20d30 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
20d40 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
20d50 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
20d60 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
20d70 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
20d80 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
20d90 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
20da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20db0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
20dc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
20dd0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
20de0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
20df0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
20e00 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
20e10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20e20 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
20e30 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
20e40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
20e50 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
20e60 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
20e70 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
20e80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20e90 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
20ea0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
20eb0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
20ec0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
20ed0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
20ee0 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
20ef0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
20f00 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
20f10 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
20f20 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
20f30 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
20f40 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
20f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20f60 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
20f70 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
20f80 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
20f90 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
20fa0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
20fb0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
20fc0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
20fd0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
20fe0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
20ff0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
21000 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
21010 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
21020 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
21030 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
21040 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
21050 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21060 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
21070 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21080 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
21090 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
210a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
210b0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
210c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
210d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
210e0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
210f0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
21100 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
21110 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
21120 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21130 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
21140 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
21150 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
21160 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
21170 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
21180 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
21190 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
211a0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
211b0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
211c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
211d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
211e0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
211f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
21200 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
21210 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
21220 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
21230 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
21240 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
21250 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
21260 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
21270 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21280 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
21290 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
212a0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
212b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
212c0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
212d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
212e0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
212f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
21300 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
21310 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
21320 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
21330 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
21340 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
21350 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
21360 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21370 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
21380 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
21390 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
213a0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
213b0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
213c0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
213d0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
213e0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
213f0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
21400 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
21410 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
21420 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
21430 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
21440 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
21450 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
21460 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
21470 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
21480 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
21490 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
214a0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
214b0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
214c0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
214d0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
214e0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
214f0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
21500 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
21510 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
21520 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
21530 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
21540 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
21550 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
21560 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
21570 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21580 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
21590 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
215a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
215b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
215c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
215d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
215e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
215f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21600 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
21610 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
21620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
21630 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21640 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
21650 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
21660 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
21670 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
21680 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
21690 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
216a0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
216b0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
216c0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
216d0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
216e0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
216f0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
21700 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
21710 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
21720 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
21730 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
21740 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
21750 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
21760 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
21770 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
21780 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
21790 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
217a0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
217b0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
217c0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
217d0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
217e0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
217f0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
21800 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
21810 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
21820 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
21830 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
21840 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
21850 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
21860 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
21870 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
21880 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
21890 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
218a0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
218b0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
218c0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
218d0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
218e0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
218f0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
21900 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
21910 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
21920 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
21930 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
21940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
21950 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
21960 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21970 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
21980 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21990 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
219a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
219b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
219c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
219d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
219e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
219f0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
21a00 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
21a10 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
21a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21a30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21a40 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
21a50 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
21a60 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
21a70 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
21a80 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
21a90 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
21aa0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
21ab0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
21ac0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
21ad0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
21ae0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
21af0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
21b00 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
21b10 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
21b20 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
21b30 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
21b40 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
21b50 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
21b60 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
21b70 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
21b80 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
21b90 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
21ba0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
21bb0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
21bc0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
21bd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21be0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
21bf0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21c00 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
21c10 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
21c20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21c30 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
21c40 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
21c50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21c60 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
21c70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21c80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
21c90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
21ca0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
21cb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21cc0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
21cd0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
21ce0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
21cf0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
21d00 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
21d10 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
21d20 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
21d30 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
21d40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21d50 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
21d60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21d70 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
21d80 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
21d90 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
21da0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
21db0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
21dc0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
21dd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
21de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21df0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
21e00 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
21e10 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
21e20 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
21e30 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
21e40 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
21e50 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
21e60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21e70 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
21e80 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
21e90 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
21ea0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
21eb0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
21ec0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
21ed0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
21ee0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
21ef0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
21f00 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
21f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
21f20 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
21f30 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
21f40 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
21f50 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
21f60 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
21f70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
21f80 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
21f90 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
21fa0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
21fb0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
21fc0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
21fd0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
21fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21ff0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
22000 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
22010 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
22020 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
22030 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
22040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22050 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
22060 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
22070 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
22080 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
22090 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
220a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
220b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
220c0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
220d0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
220e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
220f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22100 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
22110 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
22120 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
22130 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
22140 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
22150 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
22160 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
22170 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
22180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22190 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
221a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
221b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
221c0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
221d0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
221e0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
221f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22200 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
22210 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
22220 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
22230 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
22240 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
22250 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
22260 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
22270 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
22280 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
22290 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
222a0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
222b0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
222c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
222d0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
222e0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
222f0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
22300 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
22310 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
22320 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
22330 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
22340 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
22350 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
22360 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
22370 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
22380 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
22390 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
223a0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
223b0 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
223c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
223d0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
223e0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
223f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22400 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22410 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22420 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
22430 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
22440 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
22450 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
22460 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
22470 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
22480 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
22490 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
224a0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
224b0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
224c0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
224d0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
224e0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
224f0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
22500 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
22510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
22520 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
22530 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
22540 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
22550 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
22560 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
22570 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
22580 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
22590 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
225a0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
225b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
225c0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
225d0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
225e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
225f0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
22600 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
22610 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
22620 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
22630 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
22640 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
22650 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
22660 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
22670 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
22680 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
22690 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
226a0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
226b0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
226c0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
226d0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
226e0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
226f0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
22700 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
22710 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
22720 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
22730 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
22740 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
22750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22760 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
22770 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
22780 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
22790 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
227a0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
227b0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
227c0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
227d0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
227e0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
227f0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
22800 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
22810 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
22820 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
22830 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
22840 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
22850 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
22860 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
22870 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
22880 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
22890 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
228a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
228b0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
228c0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
228d0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
228e0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
228f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
22900 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
22910 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
22920 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
22930 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
22940 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
22950 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
22960 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
22970 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
22980 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
22990 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
229a0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
229b0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
229c0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
229d0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
229e0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
229f0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
22a00 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
22a10 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
22a20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
22a30 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
22a40 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
22a50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
22a60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
22a70 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
22a80 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
22a90 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
22aa0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
22ab0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
22ac0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
22ad0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
22ae0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
22af0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
22b00 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
22b10 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
22b20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
22b30 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
22b40 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
22b50 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
22b60 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
22b70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
22b80 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
22b90 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
22ba0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
22bb0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
22bc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22bd0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
22be0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
22bf0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
22c00 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
22c10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
22c20 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22c30 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
22c40 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
22c50 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
22c60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
22c70 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
22c80 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
22c90 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
22ca0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
22cb0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
22cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
22cd0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
22ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22cf0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
22d00 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
22d10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
22d30 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
22d40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
22d50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
22d60 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
22d70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
22d80 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
22d90 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
22da0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
22db0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
22dc0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
22dd0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
22de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22df0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
22e00 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
22e10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
22e20 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
22e30 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
22e40 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
22e50 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
22e60 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
22e70 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
22e80 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
22e90 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
22ea0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
22eb0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
22ec0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
22ed0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
22ee0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
22ef0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
22f00 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
22f10 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
22f20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
22f30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
22f40 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
22f50 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
22f60 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
22f70 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
22f80 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
22f90 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
22fa0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
22fb0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
22fc0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
22fd0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
22fe0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
22ff0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
23000 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
23010 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
23020 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
23030 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
23040 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
23050 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
23060 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
23070 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
23080 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
23090 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
230a0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
230b0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
230c0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
230d0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
230e0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
230f0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
23100 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
23110 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
23120 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
23130 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
23140 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
23150 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
23160 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
23170 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
23180 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
23190 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
231a0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
231b0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
231c0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
231d0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
231e0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
231f0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
23200 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
23210 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
23220 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
23230 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
23240 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23250 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23260 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
23270 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
23280 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
23290 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
232a0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
232b0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
232c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
232d0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
232e0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
232f0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
23300 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23310 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
23320 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
23330 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
23340 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
23350 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23360 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
23370 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
23380 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
23390 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
233a0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
233b0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
233c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
233d0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
233e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
233f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
23400 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
23410 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
23420 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
23430 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
23440 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
23450 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
23460 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23470 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
23480 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23490 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
234a0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
234b0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
234c0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
234d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
234e0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
234f0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
23500 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
23510 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
23520 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
23530 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
23540 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
23550 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
23560 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
23570 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
23580 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
23590 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
235a0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
235b0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
235c0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
235d0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
235e0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
235f0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
23600 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
23610 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
23620 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
23630 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
23640 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23650 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
23660 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
23670 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
23680 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
23690 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
236a0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
236b0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
236c0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
236d0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
236e0 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
236f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
23700 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
23710 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
23720 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
23730 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
23740 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
23750 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
23760 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
23770 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
23780 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
23790 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
237a0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
237b0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
237c0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
237d0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
237e0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
237f0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
23800 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
23810 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
23820 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
23830 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
23840 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
23850 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
23860 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
23870 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
23880 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
23890 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
238a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
238b0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
238c0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
238d0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
238e0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
238f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
23900 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
23910 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
23920 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
23930 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
23940 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
23950 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
23960 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
23970 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
23980 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
23990 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
239a0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
239b0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
239c0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
239d0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
239e0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
239f0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
23a00 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
23a10 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
23a20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
23a30 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
23a40 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
23a50 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
23a60 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
23a70 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
23a80 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
23a90 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
23aa0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
23ab0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
23ac0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
23ad0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
23ae0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
23af0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
23b00 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
23b10 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
23b20 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
23b30 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
23b40 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
23b50 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
23b60 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
23b70 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
23b80 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
23b90 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
23ba0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23bb0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
23bc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23bd0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
23be0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
23bf0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
23c00 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
23c10 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
23c20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
23c30 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
23c40 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
23c50 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
23c60 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
23c70 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
23c80 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
23c90 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
23ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23cb0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
23cc0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
23cd0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
23ce0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
23cf0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
23d00 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
23d10 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
23d20 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
23d30 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
23d40 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
23d50 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
23d60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23d70 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
23d80 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
23d90 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
23da0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
23db0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
23dc0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
23dd0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
23de0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
23df0 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71  23.1, it was req
23e00 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73  uired.** after s
23e10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
23e20 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20  turned anything 
23e30 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
23e40 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20  TE_ROW] that.** 
23e50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23e60 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  ] be called befo
23e70 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
23e80 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
23e90 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
23ea0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69  ).  Failure to i
23eb0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72  nvoke [sqlite3_r
23ec0 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20  eset()] in this 
23ed0 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73  way would.** res
23ee0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
23ef0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
23f00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74   from sqlite3_st
23f10 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
23f20 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  .** version 3.6.
23f30 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
23f40 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69  ep() began calli
23f50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
23f60 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74  t()] .** automat
23f70 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
23f80 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
23f90 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  er than returnin
23fa0 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
23fb0 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ].  .**.** <b>Go
23fc0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
23fd0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
23fe0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
23ff0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
24000 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
24010 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
24020 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
24030 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
24040 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
24050 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
24060 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
24070 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
24080 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
24090 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
240a0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
240b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
240c0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
240d0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
240e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
240f0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
24100 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
24110 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
24120 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
24130 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
24140 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
24150 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
24160 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
24170 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
24180 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
24190 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
241a0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
241b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
241c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
241d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
241e0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
241f0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
24200 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24210 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
24220 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
24230 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
24240 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
24250 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
24260 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
24270 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
24280 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
24290 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
242a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
242b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
242c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
242d0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
242e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
242f0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
24300 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
24310 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
24320 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
24330 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
24340 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
24350 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
24360 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
24370 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
24380 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
24390 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
243a0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
243b0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
243c0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
243d0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
243e0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
243f0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
24400 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
24410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
24420 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
24430 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
24440 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
24450 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
24460 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
24470 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
24480 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
24490 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
244a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  inter..**.** See
244b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
244c0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
244d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
244e0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
244f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
24500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24510 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
24520 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
24530 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
24540 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
24550 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
24560 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
24570 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
24580 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
24590 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
245a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
245b0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
245c0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
245d0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
245e0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
245f0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
24600 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
24610 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
24620 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
24630 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
24640 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
24650 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
24660 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
24670 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
24680 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
24690 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
246a0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
246b0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
246c0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
246d0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
246e0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
246f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
24700 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
24710 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
24720 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
24730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24740 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
24750 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
24760 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
24770 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
24780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
24790 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
247a0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
247b0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
247c0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
247d0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
247e0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
247f0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
24800 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
24810 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
24820 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
24830 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
24840 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
24850 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
24860 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
24870 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
24880 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
24890 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
248a0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
248b0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
248c0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
248d0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
248e0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
248f0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
24900 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
24910 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24920 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
24930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24940 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
24950 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
24960 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
24970 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
24980 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
24990 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
249a0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
249b0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
249c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
249d0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
249e0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
249f0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
24a00 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
24a10 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
24a20 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
24a30 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
24a40 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
24a50 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
24a60 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
24a70 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
24a80 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
24a90 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
24aa0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
24ab0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
24ac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
24ad0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
24ae0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
24af0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
24b00 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
24b10 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
24b20 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
24b30 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
24b40 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
24b50 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
24b60 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
24b70 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
24b80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24b90 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
24ba0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
24bb0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
24bc0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
24bd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24be0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
24bf0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
24c00 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
24c10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
24c20 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
24c30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24c40 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
24c50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
24c60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
24c70 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
24c80 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
24c90 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
24ca0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
24cb0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
24cc0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
24cd0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
24ce0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24cf0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
24d00 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
24d10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
24d20 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
24d30 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
24d40 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
24d50 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
24d60 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
24d70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
24d90 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
24da0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
24db0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
24dc0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
24dd0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
24de0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
24df0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
24e00 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
24e10 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
24e20 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
24e30 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
24e40 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
24e50 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
24e60 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
24e70 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
24e80 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
24e90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
24ea0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
24eb0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
24ec0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
24ed0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
24ee0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
24ef0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
24f00 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
24f10 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
24f20 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
24f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
24f40 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
24f50 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
24f60 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
24f70 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
24f80 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
24f90 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
24fa0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
24fb0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
24fc0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
24fd0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
24fe0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
24ff0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
25000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
25010 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
25020 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
25030 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
25040 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
25050 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25060 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
25070 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
25080 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
25090 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
250a0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
250b0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
250c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
250d0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
250e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
250f0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
25100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25110 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
25120 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
25130 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
25140 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
25150 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
25160 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
25170 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25180 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
25190 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
251a0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
251b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
251c0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
251d0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
251e0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
251f0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
25200 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
25210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25220 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
25230 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
25240 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25250 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
25260 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
25270 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
25280 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
25290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
252a0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
252b0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
252c0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
252d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
252e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
252f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
25300 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
25310 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
25320 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
25330 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
25340 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
25350 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
25360 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
25370 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
25380 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
25390 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
253a0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
253b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
253c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
253d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
253e0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
253f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
25400 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
25410 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25420 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
25430 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25440 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
25450 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
25460 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
25470 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
25480 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
25490 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
254a0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
254b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
254c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
254d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
254e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
254f0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
25500 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
25510 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
25520 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
25530 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
25540 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
25550 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25560 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
25570 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
25580 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
25590 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
255a0 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
255b0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
255c0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
255d0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
255e0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
255f0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
25600 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
25610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
25620 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
25630 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25640 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
25650 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
25660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25670 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
25680 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25690 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
256a0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
256b0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
256c0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
256d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
256e0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
256f0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
25700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25710 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
25720 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
25730 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
25740 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
25750 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
25760 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
25770 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
25780 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
25790 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
257a0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
257b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
257c0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
257d0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
257e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
257f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
25800 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
25810 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
25820 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
25830 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
25840 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
25850 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
25860 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
25870 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
25880 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
25890 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
258a0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
258b0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
258c0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
258d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
258e0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
258f0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
25900 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
25910 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
25920 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
25930 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
25940 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
25950 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
25960 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
25970 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
25980 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
25990 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
259a0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
259b0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
259c0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
259d0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
259e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
259f0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
25a00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
25a10 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
25a20 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
25a30 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
25a40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
25a50 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
25a60 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
25a70 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
25a80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
25a90 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
25aa0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
25ab0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
25ac0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
25ad0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
25ae0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
25af0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
25b00 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
25b10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
25b20 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
25b30 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
25b40 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
25b50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
25b60 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
25b70 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
25b80 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
25b90 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
25ba0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
25bb0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
25bc0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
25bd0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
25be0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
25bf0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
25c00 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
25c10 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
25c20 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
25c30 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
25c40 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
25c50 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
25c60 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
25c70 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
25c80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
25c90 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
25ca0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
25cb0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
25cc0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
25cd0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
25ce0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
25cf0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
25d00 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
25d10 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
25d20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
25d30 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
25d40 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
25d50 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
25d60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
25d70 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
25d80 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
25d90 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
25da0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
25db0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
25dc0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
25dd0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
25de0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
25df0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
25e00 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
25e10 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
25e20 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
25e30 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
25e40 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
25e50 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
25e60 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
25e70 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
25e80 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
25e90 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
25ea0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
25eb0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
25ec0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
25ed0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
25ee0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
25ef0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
25f00 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
25f10 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
25f20 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
25f30 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
25f40 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
25f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25f60 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
25f70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25f80 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
25f90 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
25fa0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
25fb0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
25fc0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
25fd0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
25fe0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
25ff0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
26000 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
26010 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
26020 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
26030 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
26040 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
26050 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
26060 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
26070 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
26080 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
26090 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
260a0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
260b0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
260c0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
260d0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
260e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
260f0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
26100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26110 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
26120 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
26130 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
26140 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
26150 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
26160 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
26170 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
26180 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
26190 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
261a0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
261b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
261c0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
261d0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
261e0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
261f0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
26200 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
26210 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
26220 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
26230 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
26240 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
26250 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
26260 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
26270 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
26280 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
26290 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
262a0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
262b0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
262c0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
262d0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
262e0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
262f0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
26300 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
26310 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
26320 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
26330 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
26340 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
26350 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
26360 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
26370 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
26380 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
26390 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
263a0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
263b0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
263c0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
263d0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
263e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
263f0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
26400 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
26410 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
26420 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
26430 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
26440 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
26450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
26460 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
26470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26480 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
26490 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
264a0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
264b0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
264c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
264d0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
264e0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
264f0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
26500 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
26510 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
26520 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
26530 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
26540 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
26550 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
26560 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
26570 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
26580 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
26590 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
265a0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
265b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
265c0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
265d0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
265e0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
265f0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
26600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26610 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
26620 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
26630 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
26640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26650 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
26660 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
26670 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
26680 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
26690 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
266a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
266b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
266c0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
266d0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
266e0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
266f0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
26700 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
26710 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
26720 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
26730 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
26740 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
26750 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
26760 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
26770 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
26780 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
26790 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
267a0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
267b0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
267c0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
267d0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
267e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
267f0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
26800 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
26810 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
26820 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
26830 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
26840 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
26850 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
26860 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
26870 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
26880 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
26890 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
268a0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
268b0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
268c0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
268d0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
268e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
268f0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
26900 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
26910 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
26920 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
26930 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
26940 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
26950 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
26960 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26970 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
26980 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26990 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
269a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
269b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
269c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
269d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
269e0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
269f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
26a00 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
26a10 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
26a20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
26a30 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
26a40 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
26a50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26a60 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
26a70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
26a80 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
26a90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
26aa0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
26ab0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
26ac0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
26ad0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26ae0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
26af0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
26b00 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
26b10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26b20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
26b30 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
26b40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26b50 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
26b60 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
26b70 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
26b80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26b90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26ba0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
26bb0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
26bc0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
26bd0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
26be0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
26bf0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
26c00 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
26c10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
26c20 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
26c30 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
26c40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
26c50 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
26c60 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20  ors or.** or if 
26c70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26c80 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
26c90 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
26ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
26cb0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
26cc0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
26cd0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
26ce0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
26cf0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
26d00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
26d10 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
26d20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
26d30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
26d40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
26d50 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
26d60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
26d70 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
26d80 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
26d90 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
26da0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
26db0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
26dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
26dd0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
26de0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
26df0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
26e00 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
26e10 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
26e20 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
26e30 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
26e40 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26e50 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
26e60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
26e70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
26e80 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
26e90 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
26ea0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
26eb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
26ec0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26ed0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
26ee0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
26ef0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
26f00 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
26f10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f20 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
26f30 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
26f40 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
26f50 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
26f60 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
26f70 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
26f80 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
26f90 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
26fa0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
26fb0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
26fc0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
26fd0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
26fe0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
26ff0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
27000 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
27010 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
27020 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
27030 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
27040 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
27050 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27060 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
27070 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27090 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
270a0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
270b0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
270c0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
270d0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
270e0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
270f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27100 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
27110 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
27120 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
27130 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
27140 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
27150 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
27160 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
27170 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
27180 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
27190 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
271a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
271b0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
271c0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
271d0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
271e0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
271f0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
27200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
27210 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
27220 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
27230 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27240 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
27250 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
27260 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
27270 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
27280 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
27290 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
272a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
272b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
272c0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
272d0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
272e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
272f0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
27300 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
27310 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
27320 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
27330 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
27340 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
27350 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
27360 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
27370 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
27380 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27390 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
273a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
273b0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
273c0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
273d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
273e0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
273f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
27400 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
27410 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
27420 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
27430 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
27440 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
27450 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
27460 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
27470 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
27480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27490 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
274a0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
274b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
274c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
274d0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
274e0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
274f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
27500 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
27510 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
27520 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
27530 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
27540 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
27550 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
27560 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
27570 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
27580 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
27590 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
275a0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
275b0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
275c0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
275d0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
275e0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
275f0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
27600 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
27610 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
27620 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
27630 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
27640 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
27650 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
27660 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
27670 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
27680 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
27690 72 0a 2a 2a 20 74 68 65 20 74 68 65 20 73 65 63  r.** the the sec
276a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
276b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
276c0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
276d0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
276e0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
276f0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
27700 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
27710 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
27720 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
27730 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
27740 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
27750 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
27760 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
27770 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
27780 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
27790 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
277a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
277b0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
277c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
277d0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
277e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
277f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
27800 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
27810 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
27820 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
27830 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
27840 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
27850 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
27860 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
27870 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
27880 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
27890 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
278a0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
278b0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
278c0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
278d0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
278e0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
278f0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
27900 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
27910 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
27920 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
27930 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
27940 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
27950 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
27960 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
27970 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
27980 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
27990 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
279a0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
279b0 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
279c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
279d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
279e0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
279f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
27a00 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
27a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
27a20 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
27a30 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
27a40 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
27a50 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
27a60 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
27a70 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
27a80 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
27a90 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
27aa0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
27ab0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
27ac0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
27ad0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
27ae0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
27af0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
27b00 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
27b10 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
27b20 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
27b30 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
27b40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
27b50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27b60 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
27b70 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
27b80 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
27b90 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
27ba0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
27bb0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
27bc0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
27bd0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
27be0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
27bf0 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
27c00 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
27c10 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
27c20 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
27c30 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
27c40 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
27c50 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
27c60 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
27c70 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
27c80 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
27c90 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
27ca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27cb0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
27cc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27cd0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
27ce0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
27cf0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
27d00 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
27d10 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
27d20 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
27d30 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
27d40 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
27d50 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
27d60 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
27d70 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
27d80 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
27d90 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
27da0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
27db0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
27dc0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
27dd0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
27de0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
27df0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
27e00 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
27e10 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
27e20 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
27e30 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
27e40 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
27e50 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
27e60 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
27e70 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
27e80 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
27e90 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
27ea0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
27eb0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
27ec0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
27ed0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
27ee0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
27ef0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
27f00 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
27f10 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
27f20 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
27f30 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
27f40 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
27f50 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
27f60 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
27f70 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
27f80 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
27f90 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
27fa0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
27fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
27fc0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
27fd0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
27fe0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
27ff0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
28000 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
28010 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
28020 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
28030 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
28040 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
28050 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
28060 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
28070 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
28080 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
28090 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
280a0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
280b0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
280c0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
280d0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 65 72 73 20  ss NULL poiners 
280e0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
280f0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
28100 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
28110 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
28120 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
28130 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
28140 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
28150 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
28160 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
28170 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
28180 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
28190 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
281a0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
281b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
281c0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
281d0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
281e0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
281f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
28200 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
28210 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
28220 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
28230 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
28240 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
28250 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
28260 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
28270 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
28280 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
28290 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
282a0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
282b0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
282c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
282d0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
282e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
282f0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
28300 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
28310 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
28320 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
28330 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
28340 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
28350 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
28360 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
28370 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
28380 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
28390 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
283a0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
283b0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
283c0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
283d0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
283e0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
283f0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
28400 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
28410 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
28420 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
28430 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
28440 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
28450 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
28460 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
28470 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
28480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28490 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
284a0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
284b0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
284c0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
284d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
284e0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
284f0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
28500 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
28510 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
28520 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
28530 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
28540 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
28550 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
28560 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
28570 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
28580 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
28590 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
285a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
285b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
285c0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
285d0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
285e0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
285f0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
28600 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
28610 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
28620 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
28630 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
28640 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
28650 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
28660 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
28670 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
28680 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28690 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
286a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
286b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
286c0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
286d0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
286e0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
286f0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
28700 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
28710 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
28720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
28730 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
28740 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
28750 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
28760 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
28770 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
28780 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
28790 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
287a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
287b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
287c0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
287d0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
287e0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
287f0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
28800 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
28810 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
28820 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
28830 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
28840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
28850 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
28860 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
28870 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
28880 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
28890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
288a0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
288b0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
288c0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
288d0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
288e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
288f0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
28900 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
28910 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
28920 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
28930 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
28940 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
28950 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
28960 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
28970 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
28980 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
28990 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
289a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
289b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
289c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
289d0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
289e0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
289f0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
28a00 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
28a10 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
28a20 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
28a30 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
28a40 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
28a50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28a60 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
28a70 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
28a80 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
28a90 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
28aa0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
28ab0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
28ac0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
28ad0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
28ae0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
28af0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
28b00 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
28b10 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
28b20 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
28b30 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
28b40 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
28b50 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
28b60 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
28b70 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
28b80 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
28b90 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
28ba0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
28bb0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
28bc0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
28bd0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
28be0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
28bf0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
28c00 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
28c10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28c20 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
28c30 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
28c40 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
28c50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28c60 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
28c70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28c80 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
28c90 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
28ca0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
28cb0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
28cc0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
28cd0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
28ce0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
28cf0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
28d00 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
28d10 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
28d20 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
28d30 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
28d40 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
28d50 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
28d60 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
28d70 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
28d80 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
28d90 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
28da0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
28db0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
28dc0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
28dd0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
28de0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
28df0 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
28e00 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
28e10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
28e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
28e30 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
28e40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
28e50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
28e60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
28e70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
28e80 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
28e90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
28ea0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
28eb0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
28ec0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
28ed0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
28ee0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
28ef0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
28f00 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
28f10 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
28f20 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
28f30 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
28f40 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
28f50 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
28f60 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
28f70 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
28f80 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
28f90 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
28fa0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
28fb0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
28fc0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
28fd0 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
28fe0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
28ff0 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
29000 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
29010 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
29020 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
29030 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
29040 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
29050 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
29060 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
29070 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
29080 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
29090 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
290a0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
290b0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
290c0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
290d0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
290e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
290f0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
29100 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29110 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
29120 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
29130 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
29140 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
29150 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
29160 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
29170 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
29180 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
29190 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
291a0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
291b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
291c0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
291d0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
291e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
291f0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
29200 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
29210 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
29220 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
29230 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
29240 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
29250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29260 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
29270 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
29280 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
29290 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
292a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
292b0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
292c0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
292d0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
292e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
292f0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
29300 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
29310 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
29320 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
29330 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
29340 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
29350 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
29360 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
29370 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
29380 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
29390 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
293a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
293b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
293c0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
293d0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
293e0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
293f0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
29400 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
29410 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29420 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
29430 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
29440 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
29450 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
29460 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
29470 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
29480 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
29490 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
294a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
294b0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
294c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
294d0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
294e0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
294f0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
29500 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
29510 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
29520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
29530 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
29540 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
29550 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
29560 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
29570 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
29580 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
29590 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
295a0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
295b0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
295c0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
295d0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
295e0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
295f0 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
29600 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
29610 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
29620 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
29630 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
29640 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
29650 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
29660 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
29670 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
29680 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
29690 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
296a0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
296b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
296c0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
296d0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
296e0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
296f0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
29700 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
29710 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
29720 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
29730 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
29740 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
29750 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
29760 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
29770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
29780 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
29790 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
297a0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
297b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
297c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
297d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
297e0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
297f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29800 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
29810 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29820 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
29830 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
29840 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
29850 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
29860 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
29870 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
29880 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
29890 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
298a0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
298b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
298c0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
298d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
298e0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
298f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29900 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
29910 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
29920 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
29930 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
29940 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
29950 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
29960 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
29970 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
29980 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
29990 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
299a0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
299b0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
299c0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
299d0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
299e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
299f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29a00 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
29a10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
29a20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29a30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
29a40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29a50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
29a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
29a70 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
29a80 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
29a90 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
29aa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
29ab0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
29ac0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
29ad0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
29ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
29af0 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
29b00 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
29b10 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
29b20 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
29b30 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
29b40 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
29b50 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
29b60 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
29b70 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
29b80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
29b90 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
29ba0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29bb0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
29bc0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
29bd0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
29be0 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
29bf0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
29c00 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
29c10 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
29c20 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
29c30 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
29c40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
29c50 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
29c60 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
29c70 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
29c80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
29c90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
29ca0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
29cb0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
29cc0 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
29cd0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
29ce0 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
29cf0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29d00 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
29d10 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
29d20 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
29d30 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
29d40 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
29d50 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
29d60 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
29d70 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
29d80 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
29d90 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
29da0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
29db0 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
29dc0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
29dd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
29de0 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
29df0 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
29e00 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
29e10 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
29e20 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
29e30 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
29e40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29e50 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
29e60 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
29e70 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
29e80 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
29e90 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
29ea0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
29eb0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
29ec0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
29ed0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29ee0 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
29ef0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
29f00 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
29f10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
29f20 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
29f30 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
29f40 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
29f50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
29f60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29f70 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
29f80 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
29f90 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
29fa0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
29fb0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
29fc0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
29fd0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
29fe0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
29ff0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2a000 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
2a010 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2a020 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
2a030 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
2a040 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
2a050 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
2a060 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
2a070 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
2a080 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2a090 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
2a0a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2a0b0 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
2a0c0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
2a0d0 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
2a0e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2a0f0 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
2a100 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2a110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2a120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2a130 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2a140 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2a150 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
2a160 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
2a170 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2a180 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2a190 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
2a1a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2a1b0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2a1c0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2a1d0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2a1e0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2a1f0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2a200 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2a210 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2a220 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2a230 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2a240 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
2a250 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
2a260 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
2a270 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
2a280 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a290 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2a2a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2a2b0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2a2c0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2a2d0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2a2e0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2a2f0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2a300 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2a310 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2a320 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2a330 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a340 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2a350 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2a360 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2a370 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2a380 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2a390 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2a3a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2a3b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2a3c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2a3d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2a3e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2a3f0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2a400 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2a410 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
2a420 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2a430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2a440 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2a450 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
2a460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a470 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2a480 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
2a490 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2a4a0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2a4b0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
2a4c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a4d0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
2a4e0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2a4f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a500 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2a510 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a520 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2a530 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2a540 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2a550 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2a560 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2a570 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
2a580 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2a590 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2a5a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2a5b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a5c0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2a5d0 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
2a5e0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2a5f0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2a600 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2a610 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2a620 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2a630 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2a640 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2a650 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2a660 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2a670 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2a680 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2a690 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2a6a0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2a6b0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2a6c0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2a6d0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2a6e0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2a6f0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2a700 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2a710 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2a720 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2a730 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2a740 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2a750 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2a760 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2a770 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2a780 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2a790 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2a7a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2a7b0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2a7c0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2a7d0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2a7e0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2a7f0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2a800 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2a810 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2a820 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2a830 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2a840 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2a850 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2a860 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2a870 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2a880 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2a890 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2a8a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2a8b0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a8c0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2a8d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2a8e0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2a8f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2a900 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2a910 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2a920 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2a930 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2a940 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2a950 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2a960 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
2a970 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
2a980 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
2a990 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
2a9a0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2a9b0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2a9c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2a9d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
2a9e0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
2a9f0 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2aa00 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
2aa10 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
2aa20 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
2aa30 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2aa40 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2aa50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2aa60 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2aa70 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2aa80 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2aa90 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2aaa0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2aab0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2aac0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2aad0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2aae0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2aaf0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2ab00 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2ab10 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2ab20 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2ab30 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2ab40 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2ab50 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
2ab60 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2ab70 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2ab80 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2ab90 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2aba0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2abb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2abc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2abd0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2abe0 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2abf0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2ac00 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2ac10 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2ac20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2ac30 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2ac40 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2ac50 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2ac60 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2ac70 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2ac80 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2ac90 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
2aca0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2acb0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2acc0 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
2acd0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2ace0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2acf0 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2ad00 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2ad10 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2ad20 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
2ad30 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
2ad40 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
2ad50 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
2ad60 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
2ad70 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
2ad80 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
2ad90 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
2ada0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
2adb0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
2adc0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
2add0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
2ade0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2adf0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2ae00 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2ae10 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2ae20 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ae30 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2ae40 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2ae50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ae60 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
2ae70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2ae80 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2ae90 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
2aea0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
2aeb0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
2aec0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
2aed0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
2aee0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
2aef0 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
2af00 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
2af10 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
2af20 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2af30 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2af40 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2af50 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2af60 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2af70 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
2af80 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
2af90 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
2afa0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2afb0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
2afc0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
2afd0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
2afe0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
2aff0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
2b000 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2b010 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
2b020 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2b030 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2b040 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2b050 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2b060 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2b070 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2b080 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2b090 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2b0a0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2b0b0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2b0c0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2b0d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2b0e0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2b0f0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2b100 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2b110 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2b120 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2b130 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2b140 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2b150 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2b160 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2b170 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2b180 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2b190 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2b1a0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2b1b0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2b1c0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2b1d0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2b1e0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2b1f0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2b200 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2b210 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
2b220 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2b230 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
2b240 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
2b250 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
2b260 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
2b270 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2b280 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
2b290 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b2a0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2b2b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b2c0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
2b2d0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2b2e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
2b2f0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
2b300 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
2b310 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
2b320 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
2b330 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
2b340 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
2b350 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
2b360 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
2b370 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
2b380 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
2b390 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
2b3a0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
2b3b0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2b3c0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
2b3d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b3e0 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
2b3f0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2b400 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2b410 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b420 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2b430 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
2b440 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
2b450 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
2b460 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2b470 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
2b480 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
2b490 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
2b4a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
2b4b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b4c0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
2b4d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
2b4e0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
2b4f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2b500 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b510 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
2b520 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
2b530 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
2b540 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
2b550 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
2b560 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
2b570 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
2b580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b590 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
2b5a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2b5b0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2b5c0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2b5d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2b5e0 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
2b5f0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2b600 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2b610 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
2b620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2b630 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b640 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
2b650 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2b660 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
2b670 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
2b680 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
2b690 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
2b6a0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
2b6b0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
2b6c0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
2b6d0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
2b6e0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
2b6f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2b700 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2b710 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
2b720 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
2b730 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
2b740 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
2b750 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2b760 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2b770 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2b780 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2b790 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
2b7a0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2b7b0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
2b7c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b7d0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
2b7e0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
2b7f0 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
2b800 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2b810 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2b820 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2b830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b840 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
2b850 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2b860 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
2b870 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2b880 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
2b890 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2b8a0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2b8b0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2b8c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b8d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b8e0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2b8f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2b900 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
2b910 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2b920 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
2b930 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2b940 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
2b950 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2b960 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
2b970 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
2b980 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b990 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
2b9a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2b9b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
2b9c0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
2b9d0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
2b9e0 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
2b9f0 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
2ba00 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
2ba10 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
2ba20 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
2ba30 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
2ba40 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
2ba50 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
2ba60 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
2ba70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ba80 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
2ba90 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
2baa0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
2bab0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
2bac0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
2bad0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
2bae0 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
2baf0 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
2bb00 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
2bb10 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
2bb20 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2bb30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2bb40 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2bb50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2bb60 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
2bb70 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
2bb80 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
2bb90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2bba0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
2bbb0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2bbc0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2bbd0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2bbe0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2bbf0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2bc00 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
2bc10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2bc20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2bc30 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
2bc40 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2bc50 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2bc60 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
2bc70 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
2bc80 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
2bc90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bca0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
2bcb0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2bcc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2bcd0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2bce0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2bcf0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2bd00 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
2bd10 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2bd20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2bd30 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2bd40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bd50 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2bd60 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2bd70 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2bd80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bd90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bda0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2bdb0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2bdc0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2bdd0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2bde0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2bdf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2be00 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
2be10 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2be20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2be30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2be40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2be50 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2be60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2be70 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
2be80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2be90 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
2bea0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
2beb0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
2bec0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
2bed0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
2bee0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
2bef0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
2bf00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2bf10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
2bf20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
2bf30 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
2bf40 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
2bf50 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2bf60 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
2bf70 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
2bf80 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
2bf90 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2bfa0 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
2bfb0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
2bfc0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
2bfd0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
2bfe0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
2bff0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
2c000 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2c010 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
2c020 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2c030 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2c040 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2c050 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2c060 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2c070 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
2c080 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
2c090 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2c0a0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
2c0b0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2c0c0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2c0d0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2c0e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2c0f0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2c100 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
2c110 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
2c120 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
2c130 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
2c140 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
2c150 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
2c160 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
2c170 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
2c180 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c190 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
2c1a0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2c1b0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2c1c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2c1d0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2c1e0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2c1f0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2c200 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
2c210 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2c220 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
2c230 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
2c240 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2c250 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
2c260 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
2c270 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
2c280 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2c290 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2c2a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2c2b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c2c0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2c2d0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
2c2e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2c2f0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2c300 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
2c310 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
2c320 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
2c330 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
2c340 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
2c350 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
2c360 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
2c370 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
2c380 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
2c390 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
2c3a0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
2c3b0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
2c3c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2c3d0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2c3e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2c3f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2c400 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c410 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2c420 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2c430 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2c440 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2c450 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
2c460 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
2c470 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
2c480 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
2c490 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
2c4a0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
2c4b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2c4c0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
2c4d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2c4e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2c4f0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2c500 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2c510 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2c520 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2c530 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2c540 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2c550 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c560 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2c570 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2c580 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2c590 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2c5a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2c5b0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2c5c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
2c5d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2c5e0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
2c5f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
2c600 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
2c610 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
2c620 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
2c630 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
2c640 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2c650 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
2c660 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
2c670 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c680 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c690 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
2c6a0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
2c6b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2c6c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c6d0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
2c6e0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
2c6f0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
2c700 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
2c710 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
2c720 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
2c730 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
2c740 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2c750 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
2c760 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2c770 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
2c780 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2c790 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c7a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
2c7b0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
2c7c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2c7d0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
2c7e0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2c7f0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
2c800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c810 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2c820 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2c830 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2c840 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2c850 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2c860 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
2c870 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
2c880 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c890 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2c8a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2c8b0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
2c8c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2c8d0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
2c8e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2c8f0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
2c900 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c910 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2c920 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c930 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2c940 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2c950 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
2c960 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2c970 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2c980 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
2c990 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2c9a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c9b0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
2c9c0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2c9d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c9e0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
2c9f0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2ca00 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
2ca10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2ca20 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
2ca30 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2ca40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
2ca50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2ca60 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2ca70 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2ca80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2ca90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
2caa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2cab0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2cac0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2cad0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2cae0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2caf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2cb00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2cb10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2cb20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2cb30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2cb40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2cb50 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2cb60 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2cb70 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2cb80 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
2cb90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2cba0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2cbb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2cbc0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
2cbd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2cbe0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2cbf0 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
2cc00 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
2cc10 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
2cc20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2cc30 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
2cc40 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
2cc50 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
2cc60 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2cc70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cc80 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
2cc90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2cca0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
2ccb0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
2ccc0 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
2ccd0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
2cce0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ccf0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
2cd00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2cd10 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
2cd20 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2cd30 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
2cd40 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
2cd50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2cd60 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
2cd70 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
2cd80 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
2cd90 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
2cda0 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
2cdb0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
2cdc0 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
2cdd0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
2cde0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2cdf0 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
2ce00 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
2ce10 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
2ce20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
2ce30 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
2ce40 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2ce50 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
2ce60 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2ce70 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
2ce80 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
2ce90 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
2cea0 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
2ceb0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
2cec0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
2ced0 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
2cee0 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
2cef0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
2cf00 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2cf10 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
2cf20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
2cf30 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
2cf40 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
2cf50 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
2cf60 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
2cf70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
2cf80 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
2cf90 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
2cfa0 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
2cfb0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2cfc0 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
2cfd0 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
2cfe0 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
2cff0 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
2d000 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
2d010 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
2d020 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
2d030 20 61 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64   a application d
2d040 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
2d050 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
2d060 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
2d070 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2d080 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2d090 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
2d0a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2d0b0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
2d0c0 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
2d0d0 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
2d0e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
2d0f0 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
2d100 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
2d110 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
2d120 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
2d130 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
2d140 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
2d150 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
2d160 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
2d170 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
2d180 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2d190 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2d1a0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
2d1b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
2d1c0 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
2d1d0 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
2d1e0 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
2d1f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
2d200 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
2d210 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
2d220 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
2d230 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
2d240 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
2d250 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
2d260 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
2d270 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
2d280 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d290 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
2d2a0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
2d2b0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
2d2c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
2d2d0 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
2d2e0 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
2d2f0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
2d300 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2d310 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
2d320 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
2d330 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2d340 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
2d350 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
2d360 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
2d370 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
2d380 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
2d390 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2d3a0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
2d3b0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2d3c0 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
2d3d0 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
2d3e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2d3f0 75 73 74 20 61 6c 77 61 79 20 72 65 74 75 72 6e  ust alway return
2d400 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
2d410 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
2d420 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
2d430 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
2d440 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
2d450 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
2d460 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
2d470 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
2d480 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
2d490 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
2d4a0 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
2d4b0 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
2d4c0 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
2d4d0 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
2d4e0 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
2d4f0 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
2d500 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
2d510 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
2d520 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
2d530 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
2d540 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
2d550 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
2d560 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
2d570 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
2d580 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
2d590 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
2d5a0 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
2d5b0 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
2d5c0 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
2d5d0 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
2d5e0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
2d5f0 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
2d600 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
2d610 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
2d620 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
2d630 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
2d640 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
2d650 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
2d660 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2d670 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
2d680 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d6a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2d6b0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2d6c0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2d6d0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2d6e0 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
2d6f0 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
2d700 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
2d710 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
2d720 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
2d730 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
2d740 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
2d750 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d760 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
2d770 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
2d780 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
2d790 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
2d7a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
2d7b0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
2d7c0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
2d7d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d7e0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
2d7f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2d800 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
2d810 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
2d820 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
2d830 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
2d840 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2d850 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2d860 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
2d870 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
2d880 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
2d890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d8a0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
2d8b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
2d8c0 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
2d8d0 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
2d8e0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
2d8f0 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
2d900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2d910 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
2d920 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
2d930 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
2d940 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
2d950 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
2d960 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
2d970 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
2d980 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
2d990 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
2d9a0 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
2d9b0 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
2d9c0 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
2d9d0 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
2d9e0 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
2d9f0 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
2da00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2da10 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
2da20 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2da30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2da40 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2da50 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2da60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2da70 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
2da80 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2da90 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2daa0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
2dab0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
2dac0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2dad0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2dae0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2daf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2db00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2db10 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
2db20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2db30 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2db40 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
2db50 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
2db60 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2db70 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2db80 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
2db90 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2dba0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
2dbb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2dbc0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
2dbd0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
2dbe0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
2dbf0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2dc00 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
2dc10 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2dc20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2dc30 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2dc40 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2dc50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2dc60 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2dc70 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
2dc80 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2dc90 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2dca0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2dcb0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2dcc0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2dcd0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2dce0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2dcf0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2dd00 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2dd10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2dd20 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2dd30 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
2dd40 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
2dd50 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
2dd60 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
2dd70 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2dd80 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2dd90 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2dda0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2ddb0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2ddc0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2ddd0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2dde0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2ddf0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2de00 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2de10 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
2de20 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2de30 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
2de40 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
2de50 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2de60 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2de70 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
2de80 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
2de90 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
2dea0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
2deb0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
2dec0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
2ded0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
2dee0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2def0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
2df00 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
2df10 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
2df20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2df30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
2df40 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
2df50 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2df60 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2df70 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
2df80 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
2df90 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2dfa0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
2dfb0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2dfc0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2dfd0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2dfe0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
2dff0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2e000 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2e010 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
2e020 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2e030 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
2e040 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2e050 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
2e060 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2e070 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
2e080 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
2e090 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
2e0a0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2e0b0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2e0c0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2e0d0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2e0e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2e0f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e100 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2e110 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2e120 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2e130 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e140 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
2e150 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2e160 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
2e170 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2e180 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2e190 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2e1a0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2e1b0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
2e1c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e1d0 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
2e1e0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
2e1f0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2e200 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2e210 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
2e220 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
2e230 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
2e240 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2e250 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2e260 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2e270 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2e280 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2e290 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2e2a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2e2b0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2e2c0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2e2d0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2e2e0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2e2f0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2e300 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2e310 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
2e320 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2e330 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e340 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2e350 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2e360 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2e370 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2e380 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
2e390 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
2e3a0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
2e3b0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
2e3c0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
2e3d0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
2e3e0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
2e3f0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
2e400 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
2e410 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
2e420 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
2e430 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
2e440 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2e450 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2e460 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2e470 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2e480 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2e490 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2e4a0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
2e4b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2e4c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2e4d0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2e4e0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2e4f0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2e500 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2e510 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2e520 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2e530 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2e540 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
2e550 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2e560 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2e570 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
2e580 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
2e590 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
2e5a0 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
2e5b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2e5c0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2e5d0 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2e5e0 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2e5f0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
2e600 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
2e610 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2e620 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2e630 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
2e640 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
2e650 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
2e660 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
2e670 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2e680 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2e690 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
2e6a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2e6b0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2e6c0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2e6d0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2e6e0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2e6f0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2e700 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2e710 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
2e720 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
2e730 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
2e740 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
2e750 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
2e760 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
2e770 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
2e780 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2e790 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
2e7a0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
2e7b0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
2e7c0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
2e7d0 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
2e7e0 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
2e7f0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
2e800 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
2e810 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
2e820 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
2e830 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
2e840 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
2e850 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2e860 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
2e870 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
2e880 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
2e890 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
2e8a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2e8b0 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
2e8c0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2e8d0 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2e8e0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2e8f0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2e900 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2e910 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
2e920 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
2e930 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
2e940 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
2e950 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
2e960 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
2e970 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
2e980 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
2e990 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2e9a0 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
2e9b0 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
2e9c0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
2e9d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
2e9e0 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74  ragraphs..*/.int
2e9f0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
2ea00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ea10 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
2ea20 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2ea30 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2ea40 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
2ea50 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2ea60 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2ea70 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2ea80 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2ea90 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2eaa0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
2eab0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
2eac0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
2ead0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
2eae0 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
2eaf0 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
2eb00 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
2eb10 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2eb20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
2eb30 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
2eb40 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
2eb50 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2eb60 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
2eb70 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2eb80 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
2eb90 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
2eba0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2ebb0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2ebc0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2ebd0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
2ebe0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
2ebf0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
2ec00 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
2ec10 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2ec20 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2ec30 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
2ec40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ec50 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
2ec60 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2ec70 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
2ec80 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
2ec90 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2eca0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2ecb0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2ecc0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2ecd0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2ece0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2ecf0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2ed00 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2ed10 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
2ed20 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2ed30 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
2ed40 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
2ed50 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
2ed60 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2ed70 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
2ed80 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2ed90 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
2eda0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
2edb0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2edc0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2edd0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
2ede0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
2edf0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2ee00 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
2ee10 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
2ee20 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
2ee30 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2ee40 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
2ee50 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
2ee60 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
2ee70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2ee80 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
2ee90 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
2eea0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
2eeb0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2eec0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
2eed0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
2eee0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
2eef0 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
2ef00 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
2ef10 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
2ef20 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
2ef30 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2ef40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2ef50 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
2ef60 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
2ef70 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2ef80 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
2ef90 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2efa0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
2efb0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
2efc0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
2efd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2efe0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
2eff0 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
2f000 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
2f010 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
2f020 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2f030 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
2f040 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
2f050 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
2f060 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
2f070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f080 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
2f090 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
2f0a0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
2f0b0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
2f0c0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
2f0d0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
2f0e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2f0f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2f100 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2f110 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2f120 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
2f130 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
2f140 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
2f150 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
2f160 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
2f170 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
2f180 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
2f190 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
2f1a0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
2f1b0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
2f1c0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
2f1d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
2f1e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2f1f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2f200 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
2f210 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
2f220 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
2f230 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
2f240 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
2f250 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
2f260 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
2f270 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
2f280 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2f290 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
2f2a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
2f2b0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
2f2c0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
2f2d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
2f2e0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
2f2f0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
2f300 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
2f310 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2f320 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
2f330 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
2f340 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
2f350 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2f360 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2f370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f380 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
2f390 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
2f3a0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2f3b0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2f3c0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2f3d0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2f3e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2f3f0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
2f400 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
2f410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f420 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
2f430 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
2f440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
2f450 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
2f460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f470 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
2f480 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
2f490 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
2f4a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f4b0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
2f4c0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2f4d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
2f4e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f4f0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
2f500 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
2f510 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
2f520 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
2f530 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
2f540 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
2f550 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
2f560 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
2f570 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2f580 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
2f590 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
2f5a0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
2f5b0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2f5c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f5d0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
2f5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f5f0 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
2f600 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
2f610 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2f620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
2f630 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
2f640 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
2f650 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2f660 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2f670 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
2f680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2f690 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f6a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f6b0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
2f6c0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
2f6d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
2f6e0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
2f6f0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
2f700 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
2f710 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
2f720 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f730 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
2f740 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
2f750 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2f760 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
2f770 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
2f780 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2f790 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
2f7a0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
2f7b0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
2f7c0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
2f7d0 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
2f7e0 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
2f7f0 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
2f800 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2f810 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2f820 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
2f830 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2f840 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2f850 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2f860 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
2f870 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
2f880 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
2f890 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
2f8a0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
2f8b0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
2f8c0 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
2f8d0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2f8e0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2f8f0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2f900 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2f910 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2f920 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2f930 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2f940 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
2f950 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2f960 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2f970 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2f980 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2f990 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2f9a0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2f9b0 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2f9c0 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2f9d0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2f9e0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2f9f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2fa00 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2fa10 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2fa20 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2fa30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2fa40 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
2fa50 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
2fa60 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2fa70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2fa80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
2fa90 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
2faa0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
2fab0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2fac0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
2fad0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
2fae0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
2faf0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
2fb00 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2fb10 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
2fb20 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2fb30 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
2fb40 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
2fb50 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
2fb60 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
2fb70 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
2fb80 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
2fb90 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2fba0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
2fbb0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
2fbc0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
2fbd0 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
2fbe0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
2fbf0 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
2fc00 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
2fc10 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
2fc20 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
2fc30 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
2fc40 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
2fc50 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
2fc60 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
2fc70 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2fc80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2fc90 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2fca0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2fcb0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2fcc0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2fcd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2fce0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2fcf0 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
2fd00 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
2fd10 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2fd20 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
2fd30 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
2fd40 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2fd50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
2fd60 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
2fd70 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
2fd80 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
2fd90 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
2fda0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
2fdb0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
2fdc0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
2fdd0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2fde0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
2fdf0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
2fe00 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
2fe10 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
2fe20 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
2fe30 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
2fe40 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
2fe50 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
2fe60 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
2fe70 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2fe80 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2fe90 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2fea0 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2feb0 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2fec0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
2fed0 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
2fee0 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
2fef0 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
2ff00 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
2ff10 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
2ff20 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
2ff30 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
2ff40 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
2ff50 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
2ff60 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
2ff70 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
2ff80 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
2ff90 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
2ffa0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
2ffb0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
2ffc0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
2ffd0 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
2ffe0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
2fff0 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
30000 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
30010 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
30020 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
30030 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
30040 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
30050 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
30060 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
30070 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
30080 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
30090 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
300a0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
300b0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
300c0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
300d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
300e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
300f0 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
30100 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
30110 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
30120 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
30130 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
30140 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
30150 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
30160 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
30170 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
30180 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
30190 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
301a0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
301b0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
301c0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
301d0 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
301e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
301f0 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
30200 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
30210 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
30220 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
30230 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
30240 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
30250 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
30260 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
30270 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
30280 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
30290 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
302a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
302b0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
302c0 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
302d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
302e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
302f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
30300 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
30310 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
30320 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
30330 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
30340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
30350 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
30360 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
30370 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
30380 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
30390 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54  te_hook()..** ^T
303a0 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
303b0 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
303c0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
303d0 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
303e0 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
303f0 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
30400 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
30410 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
30420 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
30430 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
30440 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ked..** ^The thi
30450 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
30460 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
30470 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
30480 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
30490 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
304a0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
304b0 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
304c0 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20  ed row..** ^The 
304d0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
304e0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
304f0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
30500 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  ow..** ^In the c
30510 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
30520 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
30530 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
30540 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
30550 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ce..**.** ^(The 
30560 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
30570 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
30580 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
30590 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
305a0 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
305b0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
305c0 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
305d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  )^.**.** ^In the
305e0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
305f0 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
30600 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
30610 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
30620 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
30630 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
30640 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
30650 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
30660 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
30670 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20  ] clause.  ^Nor 
30680 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
30690 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
306a0 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
306b0 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
306c0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
306d0 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
306e0 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
306f0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
30700 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
30710 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
30720 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
30730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
30740 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
30750 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
30760 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
30770 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
30780 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
30790 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
307a0 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
307b0 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
307c0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
307d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
307e0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
307f0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
30800 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
30810 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
30820 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
30830 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
30840 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
30850 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
30860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30870 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
30880 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
30890 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
308a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
308b0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
308c0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
308d0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
308e0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  raph..**.** ^The
308f0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
30900 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
30910 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
30920 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
30930 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
30940 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20   call.** on the 
30950 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
30960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
30970 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
30980 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44   first call on D
30990 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
309a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
309b0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64  mmit_hook()] and
309c0 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
309d0 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e  ck_hook()].** in
309e0 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69  terfaces..*/.voi
309f0 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
30a00 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
30a10 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
30a20 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
30a30 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
30a40 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
30a50 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
30a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30a70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
30a80 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
30a90 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  Cache.** KEYWORD
30aa0 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  S: {shared cache
30ab0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  }.**.** ^(This r
30ac0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
30ad0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
30ae0 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
30af0 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
30b00 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
30b10 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
30b20 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
30b30 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63  nection | connec
30b40 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65  tions].** to the
30b50 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
30b60 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
30b70 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
30b80 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e  nt is true.** an
30b90 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
30ba0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61  e argument is fa
30bb0 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  lse.)^.**.** ^Ca
30bc0 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
30bd0 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
30be0 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
30bf0 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68  e process..** Th
30c00 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
30c10 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
30c20 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72  ion 3.5.0. In pr
30c30 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
30c40 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69  SQLite,.** shari
30c50 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  ng was enabled o
30c60 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
30c70 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
30c80 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ately..**.** ^(T
30c90 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
30ca0 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
30cb0 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
30cc0 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
30cd0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
30ce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
30cf0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
30d00 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
30d10 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
30d20 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61   Existing databa
30d30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63  se connections c
30d40 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20  ontinue use the 
30d50 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20  sharing mode.** 
30d60 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65  that was in effe
30d70 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74  ct at the time t
30d80 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e  hey were opened.
30d90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
30da0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30db0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
30dc0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
30dd0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
30de0 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
30df0 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
30e00 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
30e10 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a  d otherwise.)^.*
30e20 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63  *.** ^Shared cac
30e30 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
30e40 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
30e50 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
30e60 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
30e70 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
30e80 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
30e90 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
30ea0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
30eb0 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
30ec0 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
30ed0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f  ..**.** See Also
30ee0 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65  :  [SQLite Share
30ef0 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f  d-Cache Mode].*/
30f00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
30f10 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
30f20 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
30f30 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
30f40 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
30f50 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ory.**.** ^The s
30f60 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
30f70 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
30f80 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
30f90 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ee N bytes.** of
30fa0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
30fb0 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
30fc0 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
30fd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a  y allocations.**
30fe0 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
30ff0 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20  abase library.  
31000 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
31010 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
31020 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
31030 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
31040 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
31050 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
31060 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  mory..** ^sqlite
31070 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
31080 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
31090 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
310a0 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
310b0 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
310c0 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
310d0 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
310e0 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  quested..** ^The
310f0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
31100 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e  _memory() routin
31110 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74  e is a no-op ret
31120 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69  urning zero.** i
31130 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20  f SQLite is not 
31140 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
31150 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
31160 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
31170 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31180 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
31190 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
311a0 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
311b0 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
311c0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
311d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
311e0 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61  imit64() interfa
311f0 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71  ce sets and/or q
31200 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f  ueries the.** so
31210 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  ft limit on the 
31220 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
31230 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
31240 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
31250 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74  QLite..** ^SQLit
31260 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65  e strives to kee
31270 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74  p heap memory ut
31280 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20  ilization below 
31290 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a  the soft heap.**
312a0 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69   limit by reduci
312b0 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ng the number of
312c0 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74   pages held in t
312d0 68 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a  he page cache.**
312e0 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   as heap memory 
312f0 75 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65  usages approache
31300 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  s the limit..** 
31310 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c  ^The soft heap l
31320 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62  imit is "soft" b
31330 65 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75  ecause even thou
31340 67 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65  gh SQLite strive
31350 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c  s to stay.** bel
31360 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74  ow the limit, it
31370 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65   will exceed the
31380 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68   limit rather th
31390 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61  an generate.** a
313a0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
313b0 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65   error.  In othe
313c0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66  r words, the sof
313d0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a  t heap limit .**
313e0 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
313f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  y..**.** ^The re
31400 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
31410 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
31420 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74  p_limit64() is t
31430 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68  he size of.** th
31440 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31450 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  t prior to the c
31460 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72  all.  ^If the ar
31470 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61  gument N is nega
31480 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20  tive.** then no 
31490 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74  change is made t
314a0 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  o the soft heap 
314b0 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74  limit.  Hence, t
314c0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69  he current.** si
314d0 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68  ze of the soft h
314e0 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65  eap limit can be
314f0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69   determined by i
31500 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
31510 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
31520 69 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65  it64() with a ne
31530 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e  gative argument.
31540 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
31550 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72  rgument N is zer
31560 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20  o then the soft 
31570 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69  heap limit is di
31580 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  sabled..**.** ^(
31590 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
315a0 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72  mit is not enfor
315b0 63 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65  ced in the curre
315c0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
315d0 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d  n.** if one or m
315e0 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  ore of following
315f0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20   conditions are 
31600 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  true:.**.** <ul>
31610 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66  .** <li> The sof
31620 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
31630 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20  set to zero..** 
31640 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f  <li> Memory acco
31650 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c  unting is disabl
31660 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69  ed using a combi
31670 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  nation of the.**
31680 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
31690 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
316a0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
316b0 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65  ,...) start-time
316c0 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20   option and.**  
316d0 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f      the [SQLITE_
316e0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
316f0 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  S] compile-time 
31700 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  option..** <li> 
31710 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70  An alternative p
31720 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
31730 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63  entation is spec
31740 69 66 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ifed using.**   
31750 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
31760 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
31770 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e  IG_PCACHE],...).
31780 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67  .** <li> The pag
31790 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65  e cache allocate
317a0 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d  s from its own m
317b0 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c  emory pool suppl
317c0 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b  ied.**      by [
317d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
317e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
317f0 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72  AGECACHE],...) r
31800 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  ather than.**   
31810 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70     from the heap
31820 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ..** </ul>)^.**.
31830 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  ** Beginning wit
31840 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
31850 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74   3.7.3, the soft
31860 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
31870 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72  nforced.** regar
31880 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
31890 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
318a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
318b0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a  Y_MANAGEMENT].**
318c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
318d0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
318e0 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45    With [SQLITE_E
318f0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
31900 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65  AGEMENT],.** the
31910 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
31920 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20   is enforced on 
31930 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  every memory all
31940 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75  ocation.  Withou
31950 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  t.** [SQLITE_ENA
31960 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
31970 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74  EMENT], the soft
31980 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f   heap limit is o
31990 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20  nly enforced.** 
319a0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61  when memory is a
319b0 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20  llocated by the 
319c0 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73  page cache.  Tes
319d0 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68  ting suggests th
319e0 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68  at because.** th
319f0 65 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20  e page cache is 
31a00 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20  the predominate 
31a10 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53  memory user in S
31a20 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61  QLite, most.** a
31a30 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c  pplications will
31a40 20 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74   achieve adequat
31a50 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31a60 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69  t enforcement wi
31a70 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65  thout.** the use
31a80 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   of [SQLITE_ENAB
31a90 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
31aa0 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  MENT]..**.** The
31ab0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75   circumstances u
31ac0 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74  nder which SQLit
31ad0 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74  e will enforce t
31ae0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31af0 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65  it may.** change
31b00 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
31b10 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
31b20 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
31b30 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
31b40 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74  ap_limit64(sqlit
31b50 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a  e3_int64 N);../*
31b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
31b70 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 48 65  precated Soft He
31b80 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61  ap Limit Interfa
31b90 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ce.** DEPRECATED
31ba0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
31bb0 20 64 65 70 72 65 63 61 74 65 64 20 76 65 72 73   deprecated vers
31bc0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
31bd0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
31be0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65  mit64()].** inte
31bf0 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75  rface.  This rou
31c00 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64  tine is provided
31c10 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
31c20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
31c30 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20   only.  All new 
31c40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
31c50 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b  uld use the.** [
31c60 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
31c70 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74  p_limit64()] int
31c80 65 72 66 61 63 65 20 72 61 74 68 65 72 20 74 68  erface rather th
31c90 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a  an this one..*/.
31ca0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31cb0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  D void sqlite3_s
31cc0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
31cd0 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt N);.../*.** C
31ce0 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
31cf0 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
31d00 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
31d10 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
31d20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31d30 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
31d40 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
31d50 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
31d60 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
31d70 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
31d80 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
31d90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
31da0 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
31db0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
31dc0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
31dd0 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
31de0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
31df0 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
31e00 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
31e10 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
31e20 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
31e30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
31e40 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
31e50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
31e60 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
31e70 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
31e80 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
31e90 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
31ea0 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
31eb0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
31ec0 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
31ed0 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
31ee0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
31ef0 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
31f00 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
31f10 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
31f20 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
31f30 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
31f40 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
31f50 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
31f60 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
31f70 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
31f80 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
31f90 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
31fa0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
31fb0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
31fc0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
31fd0 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
31fe0 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
31ff0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
32000 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
32010 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
32020 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
32030 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
32040 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
32050 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
32060 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
32070 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
32080 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
32090 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
320a0 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
320b0 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
320c0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
320d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
320e0 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
320f0 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
32100 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
32110 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
32120 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
32130 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
32140 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
32150 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
32160 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
32170 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
32180 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
32190 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
321a0 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
321b0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
321c0 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
321d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
321e0 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
321f0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
32200 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
32210 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
32220 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
32230 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
32240 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
32250 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
32260 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
32270 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
32280 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
32290 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
322a0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
322b0 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
322c0 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
322d0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
322e0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
322f0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
32300 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
32310 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
32320 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
32330 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
32340 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
32350 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
32360 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
32370 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
32380 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
32390 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
323a0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
323b0 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
323c0 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
323d0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
323e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
323f0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
32400 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
32410 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
32420 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
32430 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
32440 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
32450 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
32460 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
32470 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
32480 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
32490 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
324a0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
324b0 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
324c0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
324d0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
324e0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
324f0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
32500 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
32510 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
32520 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
32530 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
32540 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
32550 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
32560 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32570 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
32580 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
32590 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
325a0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
325b0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
325c0 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
325d0 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
325e0 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
325f0 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
32600 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
32610 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
32620 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
32630 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
32640 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
32650 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
32660 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
32670 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
32680 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
32690 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
326a0 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
326b0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
326c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
326d0 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
326e0 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
326f0 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
32700 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
32710 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
32720 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
32730 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
32740 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
32750 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
32760 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
32770 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
32780 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32790 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
327a0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
327b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
327c0 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
327d0 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
327e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
327f0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
32800 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
32810 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
32820 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
32830 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
32840 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
32850 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
32860 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
32870 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
32880 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
32890 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
328a0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
328b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
328c0 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
328d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
328e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
328f0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
32900 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
32910 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
32920 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
32930 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
32940 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
32950 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
32960 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
32970 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
32980 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
32990 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
329a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
329b0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
329c0 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
329d0 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
329e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
329f0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
32a00 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
32a10 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
32a20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
32a30 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
32a40 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
32a50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32a60 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
32a70 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
32a80 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
32a90 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ** SQLite extens
32aa0 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
32ab0 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
32ac0 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  e zFile..**.** ^
32ad0 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
32ae0 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50  is zProc..** ^zP
32af0 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e  roc may be 0, in
32b00 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
32b10 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
32b20 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75  y point.** defau
32b30 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
32b40 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
32b50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32b60 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
32b70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32b80 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  rns.** [SQLITE_O
32b90 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
32ba0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
32bb0 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
32bc0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66  es wrong..** ^If
32bd0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
32be0 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
32bf0 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
32c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
32c10 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
32c20 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
32c30 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c  ttempt to.** fil
32c40 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
32c50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
32c60 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
32c70 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
32c80 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
32c90 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61  alloc()]. The ca
32ca0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
32cb0 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  * should free th
32cc0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
32cd0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
32ce0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  ee()]..**.** ^Ex
32cf0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
32d00 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
32d10 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
32d20 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
32d30 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
32d40 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
32d50 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69   API,.** otherwi
32d60 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
32d70 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   be returned..**
32d80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
32d90 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
32da0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
32db0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32dc0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
32dd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
32de0 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
32df0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
32e00 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
32e10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
32e20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
32e30 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
32e40 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
32e50 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
32e60 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
32e70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
32e80 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
32e90 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
32ea0 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
32eb0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
32ec0 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
32ed0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
32ee0 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
32ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32f00 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
32f10 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
32f20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53  Loading.**.** ^S
32f30 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
32f40 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
32f50 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
32f60 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
32f70 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
32f80 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
32f90 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
32fa0 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
32fb0 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
32fc0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
32fd0 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
32fe0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
32ff0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
33000 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
33010 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
33020 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
33030 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
33040 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
33050 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
33060 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
33070 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
33080 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20  icket #1863..** 
33090 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65  ^Call the sqlite
330a0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
330b0 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
330c0 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
330d0 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  ** to turn exten
330e0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
330f0 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
33100 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
33110 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66  n.** it back off
33120 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
33130 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
33140 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
33150 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
33160 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
33170 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
33180 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63  ally Load Static
33190 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65  ally Linked Exte
331a0 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
331b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  is interface cau
331c0 73 65 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f  ses the xEntryPo
331d0 69 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74  int() function t
331e0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
331f0 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61  .** each new [da
33200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33210 6e 5d 20 74 68 61 74 20 69 73 20 63 72 65 61 74  n] that is creat
33220 65 64 2e 20 20 54 68 65 20 69 64 65 61 20 68 65  ed.  The idea he
33230 72 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45  re is that.** xE
33240 6e 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74  ntryPoint() is t
33250 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66  he entry point f
33260 6f 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20  or a statically 
33270 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78  linked SQLite ex
33280 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  tension.** that 
33290 69 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74  is to be automat
332a0 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e  ically loaded in
332b0 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
332c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
332d0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68  .**.** ^(Even th
332e0 6f 75 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f  ough the functio
332f0 6e 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77  n prototype show
33300 73 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69  s that xEntryPoi
33310 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f  nt() takes.** no
33320 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72   arguments and r
33330 65 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c  eturns void, SQL
33340 69 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74  ite invokes xEnt
33350 72 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74  ryPoint() with t
33360 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hree.** argument
33370 73 20 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e  s and expects an
33380 64 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  d integer result
33390 20 61 73 20 69 66 20 74 68 65 20 73 69 67 6e 61   as if the signa
333a0 74 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65  ture of the.** e
333b0 6e 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65  ntry point where
333c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
333d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
333e0 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  pre>.** &nbsp;  
333f0 69 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  int xEntryPoint(
33400 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 73 71  .** &nbsp;    sq
33410 6c 69 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e  lite3 *db,.** &n
33420 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 63 68  bsp;    const ch
33430 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a  ar **pzErrMsg,.*
33440 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73  * &nbsp;    cons
33450 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
33460 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a 70  _api_routines *p
33470 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20  Thunk.** &nbsp; 
33480 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   );.** </pre></b
33490 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
334a0 2a 2a 20 49 66 20 74 68 65 20 78 45 6e 74 72 79  ** If the xEntry
334b0 50 6f 69 6e 74 20 72 6f 75 74 69 6e 65 20 65 6e  Point routine en
334c0 63 6f 75 6e 74 65 72 73 20 61 6e 20 65 72 72 6f  counters an erro
334d0 72 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b  r, it should mak
334e0 65 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 70  e *pzErrMsg.** p
334f0 6f 69 6e 74 20 74 6f 20 61 6e 20 61 70 70 72 6f  oint to an appro
33500 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
33510 73 61 67 65 20 28 6f 62 74 61 69 6e 65 64 20 66  sage (obtained f
33520 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
33530 69 6e 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64 20  intf()]).** and 
33540 72 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70  return an approp
33550 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
33560 65 5d 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e 73  e].  ^SQLite ens
33570 75 72 65 73 20 74 68 61 74 20 2a 70 7a 45 72 72  ures that *pzErr
33580 4d 73 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 62  Msg.** is NULL b
33590 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68  efore calling th
335a0 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 2e  e xEntryPoint().
335b0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69    ^SQLite will i
335c0 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  nvoke.** [sqlite
335d0 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70 7a  3_free()] on *pz
335e0 45 72 72 4d 73 67 20 61 66 74 65 72 20 78 45 6e  ErrMsg after xEn
335f0 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72  tryPoint() retur
33600 6e 73 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a 20  ns.  ^If any.** 
33610 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65  xEntryPoint() re
33620 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20  turns an error, 
33630 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
33640 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
33650 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20  pen16()],.** or 
33660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
33670 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 70 72  ()] call that pr
33680 6f 76 6f 6b 65 64 20 74 68 65 20 78 45 6e 74 72  ovoked the xEntr
33690 79 50 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66 61  yPoint() will fa
336a0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  il..**.** ^Calli
336b0 6e 67 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  ng sqlite3_auto_
336c0 65 78 74 65 6e 73 69 6f 6e 28 58 29 20 77 69 74  extension(X) wit
336d0 68 20 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  h an entry point
336e0 20 58 20 74 68 61 74 20 69 73 20 61 6c 72 65 61   X that is alrea
336f0 64 79 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69 73  dy.** on the lis
33700 74 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 65  t of automatic e
33710 78 74 65 6e 73 69 6f 6e 73 20 69 73 20 61 20 68  xtensions is a h
33720 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e  armless no-op. ^
33730 4e 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  No entry point.*
33740 2a 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  * will be called
33750 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
33760 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
33770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
33780 74 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  t is opened..**.
33790 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
337a0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
337b0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
337c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
337d0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
337e0 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
337f0 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
33800 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
33810 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
33820 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
33830 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
33840 65 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61  e disables all a
33850 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
33860 6f 6e 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  ons previously.*
33870 2a 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  * registered usi
33880 6e 67 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ng [sqlite3_auto
33890 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
338a0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
338b0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
338c0 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
338d0 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
338e0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
338f0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
33900 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
33910 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
33920 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
33930 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
33940 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
33950 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
33960 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
33970 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
33980 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
33990 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
339a0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
339b0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
339c0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
339d0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
339e0 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
339f0 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
33a00 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
33a10 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
33a20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
33a30 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
33a40 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
33a50 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
33a60 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
33a70 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
33a80 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
33a90 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
33aa0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
33ab0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
33ac0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
33ad0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
33ae0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
33af0 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
33b00 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
33b10 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
33b20 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
33b30 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
33b40 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
33b50 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
33b60 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
33b70 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
33b80 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
33b90 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
33ba0 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
33bb0 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74  called a a "virt
33bc0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
33bd0 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74  ", .** defines t
33be0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
33bf0 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  n of a [virtual 
33c00 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68  tables].  .** Th
33c10 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
33c20 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20  sists mostly of 
33c30 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
33c40 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41  module..**.** ^A
33c50 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
33c60 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64  odule is created
33c70 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61   by filling in a
33c80 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69   persistent.** i
33c90 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
33ca0 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61  structure and pa
33cb0 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20  ssing a pointer 
33cc0 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65  to that instance
33cd0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
33ce0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
33cf0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
33d00 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
33d10 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74  ..** ^The regist
33d20 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
33d30 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
33d40 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
33d50 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
33d60 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
33d70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33d80 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
33d90 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
33da0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
33db0 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
33dc0 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
33dd0 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
33de0 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
33df0 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
33e00 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
33e10 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
33e20 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
33e30 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
33e40 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
33e50 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
33e60 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
33e70 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
33e80 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
33e90 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
33ea0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
33eb0 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
33ec0 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
33ed0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
33ee0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
33ef0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
33f00 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
33f10 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
33f20 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
33f30 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
33f40 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
33f50 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
33f60 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
33f70 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
33f80 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
33f90 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
33fa0 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
33fb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
33fc0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
33fd0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
33fe0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
33ff0 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
34000 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
34010 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
34020 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
34030 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
34040 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
34050 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
34060 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
34070 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
34080 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
34090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
340a0 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
340b0 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
340c0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
340d0 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
340e0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
340f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
34100 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
34110 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
34120 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
34130 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
34140 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
34150 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
34160 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
34170 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
34180 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
34190 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
341a0 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
341b0 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
341c0 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
341d0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
341e0 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
341f0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34200 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
34210 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
34220 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34230 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
34240 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34250 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
34260 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
34270 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
34280 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
34290 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
342a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
342b0 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
342c0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
342d0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
342e0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
342f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34300 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
34310 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
34320 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
34330 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
34340 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
34350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
34360 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
34370 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
34380 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  n.** KEYWORDS: s
34390 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
343a0 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
343b0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
343c0 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
343d0 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
343e0 73 20 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a  s used as part.*
343f0 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
34400 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61  l table] interfa
34410 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ce to.** pass in
34420 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
34430 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
34440 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78  eply from the [x
34450 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65  BestIndex].** me
34460 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75  thod of a [virtu
34470 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
34480 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
34490 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
344a0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
344b0 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
344c0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
344d0 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
344e0 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
344f0 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
34500 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
34510 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43  ..**.** ^(The aC
34520 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
34530 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
34540 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
34550 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
34560 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
34570 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72  e>column OP expr
34580 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
34590 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20  .** where OP is 
345a0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
345b0 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29  &gt;, or &gt;=.)
345c0 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75  ^  ^(The particu
345d0 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a  lar operator is.
345e0 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f  ** stored in aCo
345f0 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73  nstraint[].op us
34600 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ing one of the.*
34610 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  * [SQLITE_INDEX_
34620 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20  CONSTRAINT_EQ | 
34630 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
34640 53 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d  STRAINT_ values]
34650 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64  .)^.** ^(The ind
34660 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
34670 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
34680 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
34690 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f  Column.)^  ^(aCo
346a0 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
346b0 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
346c0 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
346d0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
346e0 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
346f0 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
34700 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
34710 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
34720 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29  e if it cannot.)
34730 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74  ^.**.** ^The opt
34740 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
34750 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
34760 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
34770 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
34780 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
34790 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
347a0 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
347b0 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
347c0 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
347d0 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
347e0 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
347f0 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
34800 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
34810 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72  .** ^The aConstr
34820 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
34830 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
34840 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61  clause terms tha
34850 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e  t are.** relevan
34860 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  t to the particu
34870 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
34880 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
34890 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74  .**.** ^Informat
348a0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
348b0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
348c0 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
348d0 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20  rBy[]..** ^Each 
348e0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
348f0 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
34900 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
34910 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
34920 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  The [xBestIndex]
34930 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
34940 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
34950 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
34960 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
34970 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
34980 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
34990 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65  r.  ^If argvInde
349a0 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
349b0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
349c0 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
349d0 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
349e0 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
349f0 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
34a00 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
34a10 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
34a20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^(If aConstraint
34a30 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
34a40 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
34a50 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
34a60 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
34a70 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
34a80 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
34a90 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
34aa0 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
34ab0 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  SQLite.)^.**.** 
34ac0 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20  ^The idxNum and 
34ad0 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
34ae0 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
34af0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
34b00 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
34b10 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33  od..** ^[sqlite3
34b20 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
34b30 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
34b40 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
34b50 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
34b60 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
34b70 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f  * ^The orderByCo
34b80 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
34b90 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
34ba0 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
34bb0 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
34bc0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
34bd0 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
34be0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
34bf0 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
34c00 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
34c10 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
34c20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73  d..**.** ^The es
34c30 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
34c40 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
34c50 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
34c60 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
34c70 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
34c80 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
34c90 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
34ca0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
34cb0 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
34cc0 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
34cd0 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
34ce0 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
34cf0 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
34d00 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
34d10 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
34d20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
34d30 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
34d40 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
34d50 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
34d60 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
34d70 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
34d80 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
34d90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
34da0 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
34db0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
34dc0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
34dd0 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
34de0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
34df0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
34e00 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
34e10 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
34e20 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
34e30 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
34e40 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
34e50 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
34e60 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
34e70 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
34e80 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
34e90 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
34ea0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
34eb0 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
34ec0 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
34ed0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
34ee0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
34ef0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
34f00 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
34f10 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
34f20 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
34f30 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
34f40 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
34f50 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
34f60 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
34f70 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
34f80 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
34f90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
34fa0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
34fb0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
34fc0 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
34fd0 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
34fe0 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
34ff0 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
35000 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
35010 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
35020 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
35030 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
35040 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
35050 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
35060 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
35070 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
35080 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
35090 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
350a0 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
350b0 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
350c0 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
350d0 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
350e0 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
350f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
35100 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
35110 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
35120 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
35130 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
35140 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
35150 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
35160 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
35170 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
35180 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
35190 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
351a0 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
351b0 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
351c0 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
351d0 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
351e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
351f0 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
35200 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
35210 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
35220 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
35230 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
35240 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
35250 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
35260 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
35270 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
35280 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
35290 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
352a0 61 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20  able Constraint 
352b0 4f 70 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a  Operator Codes.*
352c0 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f  *.** These macro
352d0 73 20 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c  s defined the al
352e0 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72  lowed values for
352f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
35300 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f  _index_info].aCo
35310 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69  nstraint[].op fi
35320 65 6c 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65  eld.  Each value
35330 20 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61   represents.** a
35340 6e 20 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20  n operator that 
35350 69 73 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e  is part of a con
35360 73 74 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20  straint term in 
35370 74 68 65 20 77 48 45 52 45 20 63 6c 61 75 73 65  the wHERE clause
35380 20 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74   of.** a query t
35390 68 61 74 20 75 73 65 73 20 61 20 5b 76 69 72 74  hat uses a [virt
353a0 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23  ual table]..*/.#
353b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
353c0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
353d0 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  Q    2.#define S
353e0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
353f0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23  TRAINT_GT    4.#
35400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
35410 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
35420 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53  E    8.#define S
35430 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
35440 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a  TRAINT_LT    16.
35450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
35460 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
35470 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  GE    32.#define
35480 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
35490 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36  NSTRAINT_MATCH 6
354a0 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
354b0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69  F: Register A Vi
354c0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
354d0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a  ementation.**.**
354e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
354f0 20 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 67   are used to reg
35500 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72  ister a new [vir
35510 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
35520 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64  e] name..** ^Mod
35530 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ule names must b
35540 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66  e registered bef
35550 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20  ore.** creating 
35560 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
35570 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20  able] using the 
35580 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72  module and befor
35590 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65  e using a.** pre
355a0 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61  existing [virtua
355b0 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65  l table] for the
355c0 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   module..**.** ^
355d0 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  The module name 
355e0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e  is registered on
355f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35600 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
35610 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  fied.** by the f
35620 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
35630 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
35640 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65  e module is give
35650 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63  n by the .** sec
35660 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
35670 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
35680 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
35690 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  r to.** the impl
356a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
356b0 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
356c0 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65   module].   ^The
356d0 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d   fourth.** param
356e0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
356f0 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61  rary client data
35700 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
35710 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
35720 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72  ** into the [xCr
35730 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
35740 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
35750 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
35760 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e  e module.** when
35770 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74   a new virtual t
35780 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67  able is be being
35790 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e   created or rein
357a0 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  itialized..**.**
357b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
357c0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
357d0 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 61   interface has a
357e0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
357f0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
35800 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
35810 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70  ructor for the p
35820 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51  ClientData.  ^SQ
35830 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76  Lite will.** inv
35840 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
35850 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20  or function (if 
35860 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  it is not NULL) 
35870 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e  when SQLite.** n
35880 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74  o longer needs t
35890 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70  he pClientData p
358a0 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65  ointer.  ^The de
358b0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c  structor will al
358c0 73 6f 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64  so.** be invoked
358d0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
358e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
358f0 6f 64 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73  odule_v2() fails
35900 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35910 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
35920 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
35930 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
35940 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
35950 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20  odule_v2() with 
35960 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75  a NULL.** destru
35970 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ctor..*/.int sql
35980 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
35990 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
359a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
359b0 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
359c0 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
359d0 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
359e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
359f0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
35a00 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
35a10 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
35a20 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
35a30 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
35a40 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
35a50 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
35a60 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a  Data          /*
35a70 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
35a80 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
35a90 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  t */.);.int sqli
35aa0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
35ab0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
35ac0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
35ad0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
35ae0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
35af0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
35b00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
35b10 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
35b20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
35b30 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
35b40 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
35b50 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *p,   /* Methods
35b60 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
35b70 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65  */.  void *pClie
35b80 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20  ntData,         
35b90 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
35ba0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
35bb0 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
35bc0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
35bd0 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
35be0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
35bf0 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
35c00 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
35c10 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
35c20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
35c30 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
35c40 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69  .**.** Every [vi
35c50 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
35c60 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  le] implementati
35c70 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
35c80 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62  ss.** of this ob
35c90 6a 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65  ject to describe
35ca0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e   a particular in
35cb0 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65  stance.** of the
35cc0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
35cd0 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
35ce0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c   will.** be tail
35cf0 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
35d00 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
35d10 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
35d20 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  ntation..** The 
35d30 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20  purpose of this 
35d40 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f  superclass is to
35d50 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20   define certain 
35d60 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a  fields that are.
35d70 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  ** common to all
35d80 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
35d90 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tations..**.** ^
35da0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
35db0 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
35dc0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
35dd0 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
35de0 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
35df0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35e00 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45  mprintf()] to zE
35e10 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
35e20 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
35e30 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
35e40 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
35e50 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
35e60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
35e70 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
35e80 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
35e90 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
35ea0 67 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65  g.  ^After the e
35eb0 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
35ec0 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20  is delivered up 
35ed0 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70  to the client ap
35ee0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73  plication, the s
35ef0 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75  tring will be au
35f00 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66  tomatically.** f
35f10 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  reed by sqlite3_
35f20 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a  free() and the z
35f30 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c  ErrMsg field wil
35f40 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a  l be zeroed..*/.
35f50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
35f60 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
35f70 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
35f80 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
35f90 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
35fa0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
35fb0 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
35fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35fd0 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55    /* NO LONGER U
35fe0 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a  SED */.  char *z
35ff0 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20  ErrMsg;         
36000 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
36010 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73  r message from s
36020 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
36030 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
36040 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
36050 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
36060 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
36070 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
36080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36090 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
360a0 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a   Cursor Object.*
360b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
360c0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
360d0 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63  {virtual table c
360e0 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65  ursor}.**.** Eve
360f0 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
36100 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
36110 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
36120 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
36130 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  ** following str
36140 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69  ucture to descri
36150 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20  be cursors that 
36160 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a  point into the.*
36170 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
36180 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a  ] and are used.*
36190 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67  * to loop throug
361a0 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  h the virtual ta
361b0 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72  ble.  Cursors ar
361c0 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
361d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
361e0 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78  module.xOpen | x
361f0 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  Open] method of 
36200 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61  the module and a
36210 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  re destroyed.** 
36220 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
36230 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20  module.xClose | 
36240 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20  xClose] method. 
36250 20 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65   Cursors are use
36260 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69  d.** by the [xFi
36270 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20  lter], [xNext], 
36280 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e  [xEof], [xColumn
36290 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20  ], and [xRowid] 
362a0 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68  methods.** of th
362b0 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
362c0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
362d0 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e  ation will defin
362e0 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  e.** the content
362f0 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72   of a cursor str
36300 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69  ucture to suit i
36310 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a  ts own needs..**
36320 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c  .** This supercl
36330 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72  ass exists in or
36340 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69  der to define fi
36350 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73  elds of the curs
36360 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  or that.** are c
36370 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70  ommon to all imp
36380 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f  lementations..*/
36390 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
363a0 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20  vtab_cursor {.  
363b0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
363c0 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72  tab;      /* Vir
363d0 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68  tual table of th
363e0 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f  is cursor */.  /
363f0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
36400 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36410 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
36420 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
36430 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
36440 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
36450 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f  are The Schema O
36460 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  f A Virtual Tabl
36470 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43  e.**.** ^The [xC
36480 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e  reate] and [xCon
36490 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66  nect] methods of
364a0 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74   a.** [virtual t
364b0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c  able module] cal
364c0 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  l this interface
364d0 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74  .** to declare t
364e0 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e  he format (the n
364f0 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70  ames and datatyp
36500 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
36510 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72  s) of.** the vir
36520 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79  tual tables they
36530 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69   implement..*/.i
36540 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
36550 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
36560 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
36570 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
36580 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
36590 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
365a0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
365b0 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61  .** ^(Virtual ta
365c0 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
365d0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
365e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
365f0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
36600 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
36610 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
36620 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
36630 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
36640 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
36650 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
36660 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
36670 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
36680 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
36690 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
366a0 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20   API makes sure 
366b0 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  a global version
366c0 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77   of a function w
366d0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
366e0 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d  .** name and num
366f0 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
36700 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f  s exists.  If no
36710 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65   such function e
36720 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20  xists.** before 
36730 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c  this API is call
36740 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69  ed, a new functi
36750 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e  on is created.)^
36760 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74    ^The implement
36770 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
36780 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
36790 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
367a0 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
367b0 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
367c0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
367d0 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
367e0 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
367f0 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
36800 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
36810 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
36820 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
36830 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
36840 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74   by a [virtual t
36850 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  able]..*/.int sq
36860 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
36870 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
36880 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
36890 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
368a0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
368b0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
368c0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
368d0 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
368e0 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
368f0 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
36900 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
36910 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
36920 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
36930 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
36940 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
36950 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
36960 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
36970 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
36980 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
36990 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
369a0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
369b0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
369c0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
369d0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
369e0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
369f0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
36a00 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
36a10 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
36a20 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
36a30 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
36a40 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
36a50 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ent..*/../*.** C
36a60 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c  API3REF: A Handl
36a70 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e To An Open BLO
36a80 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  B.** KEYWORDS: {
36a90 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c  BLOB handle} {BL
36aa0 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a  OB handles}.**.*
36ab0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
36ac0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
36ad0 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
36ae0 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a  BLOB on which.**
36af0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
36b00 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
36b10 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20  l BLOB I/O] can 
36b20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  be performed..**
36b30 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69   ^Objects of thi
36b40 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74  s type are creat
36b50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
36b60 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61  lob_open()].** a
36b70 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  nd destroyed by 
36b80 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
36b90 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ose()]..** ^The 
36ba0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
36bb0 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
36bc0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
36bd0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
36be0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
36bf0 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
36c00 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
36c10 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54   the BLOB..** ^T
36c20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
36c30 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
36c40 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
36c50 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
36c60 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
36c70 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
36c80 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
36c90 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
36ca0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
36cb0 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
36cc0 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e  ntal I/O.**.** ^
36cd0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73  (This interfaces
36ce0 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68   opens a [BLOB h
36cf0 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20  andle | handle] 
36d00 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61  to the BLOB loca
36d10 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52  ted.** in row iR
36d20 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  ow, column zColu
36d30 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
36d40 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
36d50 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
36d60 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c  rds, the same BL
36d70 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  OB that would be
36d80 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a   selected by:.**
36d90 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
36da0 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20   SELECT zColumn 
36db0 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20  FROM zDb.zTable 
36dc0 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20  WHERE [rowid] = 
36dd0 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29  iRow;.** </pre>)
36de0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
36df0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
36e00 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
36e10 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70  n the BLOB is op
36e20 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a  ened for read.**
36e30 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73   and write acces
36e40 73 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72  s. ^If it is zer
36e50 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f  o, the BLOB is o
36e60 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61  pened for read a
36e70 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73  ccess..** ^It is
36e80 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
36e90 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74   open a column t
36ea0 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
36eb0 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61  n index or prima
36ec0 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77  ry .** key for w
36ed0 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72  riting. ^If [for
36ee0 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
36ef0 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65  ints] are enable
36f00 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74  d, it is .** not
36f10 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65   possible to ope
36f20 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  n a column that 
36f30 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68  is part of a [ch
36f40 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69  ild key] for wri
36f50 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  ting..**.** ^Not
36f60 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  e that the datab
36f70 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20  ase name is not 
36f80 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61  the filename tha
36f90 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  t contains.** th
36fa0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72  e database but r
36fb0 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c  ather the symbol
36fc0 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ic name of the d
36fd0 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20  atabase that.** 
36fe0 61 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68  appears after th
36ff0 65 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65  e AS keyword whe
37000 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
37010 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e  s connected usin
37020 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e  g [ATTACH]..** ^
37030 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
37040 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
37050 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
37060 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72   "main"..** ^For
37070 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
37080 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
37090 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
370a0 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b   ^(On success, [
370b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
370c0 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e  turned and the n
370d0 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ew [BLOB handle]
370e0 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74   is written.** t
370f0 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72  o *ppBlob. Other
37100 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
37110 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
37120 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20   and *ppBlob is 
37130 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e  set.** to be a n
37140 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a  ull pointer.)^.*
37150 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
37160 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62   sets the [datab
37170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37180 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
37190 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73  essage.** access
371a0 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65  ible via [sqlite
371b0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64  3_errcode()] and
371c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
371d0 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a  ()] and related.
371e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e  ** functions. ^N
371f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70  ote that the *pp
37200 42 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73  Blob variable is
37210 20 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69   always initiali
37220 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20  zed in a.** way 
37230 74 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61  that makes it sa
37240 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71  fe to invoke [sq
37250 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
37260 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a  ()] on *ppBlob.*
37270 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
37280 74 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  the success or f
37290 61 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72  ailure of this r
372a0 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  outine..**.** ^(
372b0 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20  If the row that 
372c0 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f  a BLOB handle po
372d0 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66  ints to is modif
372e0 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50  ied by an.** [UP
372f0 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c  DATE], [DELETE],
37300 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c   or by [ON CONFL
37310 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74  ICT] side-effect
37320 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c  s.** then the BL
37330 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72  OB handle is mar
37340 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22  ked as "expired"
37350 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75  ..** This is tru
37360 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20  e if any column 
37370 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68  of the row is ch
37380 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f  anged, even a co
37390 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68  lumn.** other th
373a0 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42  an the one the B
373b0 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70  LOB handle is op
373c0 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c  en on.)^.** ^Cal
373d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
373e0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
373f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
37400 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20  ite()] for.** a 
37410 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e  expired BLOB han
37420 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e  dle fail with an
37430 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
37440 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
37450 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69  ** ^(Changes wri
37460 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42  tten into a BLOB
37470 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c   prior to the BL
37480 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20  OB expiring are 
37490 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  not.** rolled ba
374a0 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61  ck by the expira
374b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42  tion of the BLOB
374c0 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20  .  Such changes 
374d0 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a  will eventually.
374e0 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65  ** commit if the
374f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
37500 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
37510 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55  tion.)^.**.** ^U
37520 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
37530 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
37540 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 72  terface to deter
37550 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66  mine the size of
37560 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62  .** the opened b
37570 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20  lob.  ^The size 
37580 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f  of a blob may no
37590 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  t be changed by 
375a0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
375b0 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44  e.  Use the [UPD
375c0 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  ATE] SQL command
375d0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73   to change the s
375e0 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62  ize of a.** blob
375f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
37600 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
37610 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lob()] and [sqli
37620 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
37630 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65  lob()] interface
37640 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69  s.** and the bui
37650 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d  lt-in [zeroblob]
37660 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61   SQL function ca
37670 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65  n be used, if de
37680 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65  sired,.** to cre
37690 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65  ate an empty, ze
376a0 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69  ro-filled blob i
376b0 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20  n which to read 
376c0 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a  or write using.*
376d0 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  * this interface
376e0 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ..**.** To avoid
376f0 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b   a resource leak
37700 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c  , every open [BL
37710 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c  OB handle] shoul
37720 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  d eventually.** 
37730 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61  be released by a
37740 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37750 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
37760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37770 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
37780 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
37790 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
377a0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
377b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
377c0 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
377d0 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
377e0 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
377f0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
37800 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
37810 33 52 45 46 3a 20 4d 6f 76 65 20 61 20 42 4c 4f  3REF: Move a BLO
37820 42 20 48 61 6e 64 6c 65 20 74 6f 20 61 20 4e 65  B Handle to a Ne
37830 77 20 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  w Row.**.** ^Thi
37840 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
37850 65 64 20 74 6f 20 6d 6f 76 65 20 61 6e 20 65 78  ed to move an ex
37860 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64  isting blob hand
37870 6c 65 20 73 6f 20 74 68 61 74 20 69 74 20 70 6f  le so that it po
37880 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 64 69 66  ints.** to a dif
37890 66 65 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  ferent row of th
378a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
378b0 74 61 62 6c 65 2e 20 5e 54 68 65 20 6e 65 77 20  table. ^The new 
378c0 72 6f 77 20 69 73 20 69 64 65 6e 74 69 66 69 65  row is identifie
378d0 64 0a 2a 2a 20 62 79 20 74 68 65 20 72 6f 77 69  d.** by the rowi
378e0 64 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  d value passed a
378f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
37900 75 6d 65 6e 74 2e 20 4f 6e 6c 79 20 74 68 65 20  ument. Only the 
37910 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20 63 68  row can be.** ch
37920 61 6e 67 65 64 2e 20 5e 54 68 65 20 64 61 74 61  anged. ^The data
37930 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20  base, table and 
37940 63 6f 6c 75 6d 6e 20 6f 6e 20 77 68 69 63 68 20  column on which 
37950 74 68 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20  the blob handle 
37960 69 73 20 6f 70 65 6e 0a 2a 2a 20 72 65 6d 61 69  is open.** remai
37970 6e 20 74 68 65 20 73 61 6d 65 2e 20 4d 6f 76 69  n the same. Movi
37980 6e 67 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62  ng an existing b
37990 6c 6f 62 20 68 61 6e 64 6c 65 20 74 6f 20 61 20  lob handle to a 
379a0 6e 65 77 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a  new row can be.*
379b0 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 63 6c  * faster than cl
379c0 6f 73 69 6e 67 20 74 68 65 20 65 78 69 73 74 69  osing the existi
379d0 6e 67 20 68 61 6e 64 6c 65 20 61 6e 64 20 6f 70  ng handle and op
379e0 65 6e 69 6e 67 20 61 20 6e 65 77 20 6f 6e 65 2e  ening a new one.
379f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 6e 65 77  .**.** ^(The new
37a00 20 72 6f 77 20 6d 75 73 74 20 6d 65 65 74 20 74   row must meet t
37a10 68 65 20 73 61 6d 65 20 63 72 69 74 65 72 69 61  he same criteria
37a20 20 61 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33   as for [sqlite3
37a30 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a  _blob_open()] -.
37a40 2a 2a 20 69 74 20 6d 75 73 74 20 65 78 69 73 74  ** it must exist
37a50 20 61 6e 64 20 74 68 65 72 65 20 6d 75 73 74 20   and there must 
37a60 62 65 20 65 69 74 68 65 72 20 61 20 62 6c 6f 62  be either a blob
37a70 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65 20 73   or text value s
37a80 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 74 68 65 20  tored in.** the 
37a90 6e 6f 6d 69 6e 61 74 65 64 20 63 6f 6c 75 6d 6e  nominated column
37aa0 2e 29 5e 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .)^ ^If the new 
37ab0 72 6f 77 20 69 73 20 6e 6f 74 20 70 72 65 73 65  row is not prese
37ac0 6e 74 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2c  nt in the table,
37ad0 20 6f 72 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65   or if.** it doe
37ae0 73 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20  s not contain a 
37af0 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c  blob or text val
37b00 75 65 2c 20 6f 72 20 69 66 20 61 6e 6f 74 68 65  ue, or if anothe
37b10 72 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  r error occurs, 
37b20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72  an.** SQLite err
37b30 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
37b40 6e 65 64 20 61 6e 64 20 74 68 65 20 62 6c 6f 62  ned and the blob
37b50 20 68 61 6e 64 6c 65 20 69 73 20 63 6f 6e 73 69   handle is consi
37b60 64 65 72 65 64 20 61 62 6f 72 74 65 64 2e 0a 2a  dered aborted..*
37b70 2a 20 5e 41 6c 6c 20 73 75 62 73 65 71 75 65 6e  * ^All subsequen
37b80 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
37b90 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
37ba0 2c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  , [sqlite3_blob_
37bb0 77 72 69 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  write()] or.** [
37bc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f  sqlite3_blob_reo
37bd0 70 65 6e 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f  pen()] on an abo
37be0 72 74 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65  rted blob handle
37bf0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74   immediately ret
37c00 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 42  urn.** SQLITE_AB
37c10 4f 52 54 2e 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  ORT. ^Calling [s
37c20 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
37c30 73 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74  s()] on an abort
37c40 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65 0a 2a  ed blob handle.*
37c50 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  * always returns
37c60 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
37c70 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
37c80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
37c90 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20  ndle error code 
37ca0 61 6e 64 20 6d 65 73 73 61 67 65 2e 0a 2a 2f 0a  and message..*/.
37cb0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
37cc0 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
37cd0 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 73 71 6c 69  blob_reopen(sqli
37ce0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 73 71 6c 69  te3_blob *, sqli
37cf0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  te3_int64);../*.
37d00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
37d10 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
37d20 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61  .**.** ^Closes a
37d30 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
37d40 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  dle]..**.** ^Clo
37d50 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
37d60 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
37d70 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
37d80 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
37d90 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
37da0 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
37db0 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
37dc0 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
37dd0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
37de0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b  nnection is in [
37df0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d  autocommit mode]
37e00 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69  ..** ^If any wri
37e10 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
37e20 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
37e30 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
37e40 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
37e50 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
37e60 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
37e70 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c   fit..**.** ^(Cl
37e80 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f  osing the BLOB o
37e90 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20  ften forces the 
37ea0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74  changes.** out t
37eb0 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66  o disk and so if
37ec0 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20   any I/O errors 
37ed0 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c  occur, they will
37ee0 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a   likely occur.**
37ef0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
37f00 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  n the BLOB is cl
37f10 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72  osed.  Any error
37f20 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72  s that occur dur
37f30 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61  ing.** closing a
37f40 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61  re reported as a
37f50 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
37f60 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   value.)^.**.** 
37f70 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  ^(The BLOB is cl
37f80 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
37f90 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74  ally.  Even if t
37fa0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
37fb0 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  rns.** an error 
37fc0 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69  code, the BLOB i
37fd0 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29  s still closed.)
37fe0 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ^.**.** ^Calling
37ff0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
38000 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  th a null pointe
38010 72 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64  r (such as would
38020 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   be returned.** 
38030 62 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c  by a failed call
38040 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
38050 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20  b_open()]) is a 
38060 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
38070 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
38080 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  lob_close(sqlite
38090 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
380a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
380b0 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
380c0 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
380d0 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73  * ^Returns the s
380e0 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20  ize in bytes of 
380f0 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69  the BLOB accessi
38100 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20  ble via the .** 
38110 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65  successfully ope
38120 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  ned [BLOB handle
38130 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72  ] in its only ar
38140 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a  gument.  ^The.**
38150 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f   incremental blo
38160 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63  b I/O routines c
38170 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20  an only read or 
38180 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73  overwriting exis
38190 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e  ting.** blob con
381a0 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f  tent; they canno
381b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  t change the siz
381c0 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a  e of a blob..**.
381d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
381e0 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
381f0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
38200 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
38210 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
38220 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
38230 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
38240 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
38250 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
38260 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
38270 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
38280 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
38290 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
382a0 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
382b0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
382c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
382d0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
382e0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
382f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38300 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74  blob_bytes(sqlit
38310 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
38320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61  ** CAPI3REF: Rea
38330 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c  d Data From A BL
38340 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
38350 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
38360 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
38370 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d  o read data from
38380 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
38390 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a  andle] into a.**
383a0 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64   caller-supplied
383b0 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73   buffer. N bytes
383c0 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
383d0 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ied into buffer 
383e0 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70  Z.** from the op
383f0 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
38400 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
38410 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  set.)^.**.** ^If
38420 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
38430 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62  is less than N b
38440 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
38450 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a  d of the BLOB,.*
38460 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
38470 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
38480 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
38490 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66  .  ^If N or iOff
384a0 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  set is.** less t
384b0 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54  han zero, [SQLIT
384c0 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
384d0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
384e0 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68   is read..** ^Th
384f0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c  e size of the bl
38500 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  ob (and hence th
38510 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
38520 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
38530 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
38540 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
38550 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
38560 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
38570 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
38580 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e   to read from an
38590 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
385a0 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
385b0 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
385c0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
385d0 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ORT]..**.** ^(On
385e0 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
385f0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65  3_blob_read() re
38600 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
38610 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
38620 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
38630 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
38640 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
38650 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
38660 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
38670 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
38680 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
38690 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
386a0 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
386b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
386c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
386d0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
386e0 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
386f0 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
38700 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
38710 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
38720 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
38730 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
38740 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
38750 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
38760 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
38770 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
38780 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
38790 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
387a0 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
387b0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
387c0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
387d0 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69  oid *Z, int N, i
387e0 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
387f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72  .** CAPI3REF: Wr
38800 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20  ite Data Into A 
38810 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
38820 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ly.**.** ^This f
38830 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
38840 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e  to write data in
38850 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  to an open [BLOB
38860 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a   handle] from a.
38870 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
38880 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79  ed buffer. ^N by
38890 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
388a0 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
388b0 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f  buffer Z.** into
388c0 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
388d0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
388e0 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
388f0 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20  * ^If the [BLOB 
38900 68 61 6e 64 6c 65 5