/ Hex Artifact Content
Login

Artifact 795e12e8f3c4d3fe3a4f30656c1cd13c6ea2bb0a:


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 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
8580: 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ll guarantee tha
8590: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
85a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
85b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
85c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
85d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
85e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
85f0: 61 74 68 6e 61 6d 65 28 29 2e 20 20 5e 53 51 4c  athname().  ^SQL
8600: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
8610: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
8620: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
8630: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
8640: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
8650: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
8660: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
8670: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
8680: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
8690: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
86a0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
86b0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
86c0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
86d0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
86e0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
86f0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
8700: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
8710: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8720: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
8730: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
8740: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
8750: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
8760: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
8770: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
8780: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
8790: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
87a0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
87b0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
87c0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
87d0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
87e0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
87f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8800: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
8810: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8820: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
8830: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
8840: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
8850: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8860: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
8870: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
8880: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
8890: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
88a0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
88b0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
88c0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
88d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
88e0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
88f0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
8900: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
8910: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
8920: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
8930: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
8940: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8950: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
8960: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
8970: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
8980: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
8990: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
89a0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
89b0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
89c0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
89d0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
89e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
89f0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
8a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
8a10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8a20: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8a30: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
8a40: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8a50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8a60: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
8a70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8a80: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
8a90: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8aa0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
8ab0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8ac0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
8ad0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8ae0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
8af0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8b00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
8b10: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
8b20: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
8b30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
8b40: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
8b50: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
8b60: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
8b70: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
8b80: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
8b90: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
8ba0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
8bb0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
8bc0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
8bd0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
8be0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
8bf0: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
8c00: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
8c10: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
8c20: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
8c30: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
8c40: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
8c50: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
8c60: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
8c70: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
8c80: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
8c90: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
8ca0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
8cb0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
8cc0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
8cd0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
8ce0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
8cf0: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
8d00: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
8d10: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
8d20: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
8d30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
8d40: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
8d50: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8d60: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8d70: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
8d80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8d90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8da0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
8db0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
8dc0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
8dd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
8de0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8df0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
8e00: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
8e10: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
8e20: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8e30: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
8e40: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8e50: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8e60: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8e70: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
8e80: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
8e90: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
8ea0: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
8eb0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
8ec0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8ed0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
8ee0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
8ef0: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
8f00: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
8f10: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
8f20: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
8f30: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
8f40: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
8f50: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
8f60: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
8f70: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
8f80: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
8f90: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8fa0: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
8fb0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
8fc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
8fd0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
8fe0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
8ff0: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
9000: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
9010: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
9020: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
9030: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
9040: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
9050: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9060: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
9070: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
9080: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
9090: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
90a0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
90b0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
90c0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
90d0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
90e0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
90f0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
9100: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
9110: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
9120: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
9130: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
9140: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
9150: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
9160: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
9170: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
9180: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
9190: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
91a0: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
91b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
91c0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
91d0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
91e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
91f0: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
9200: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
9210: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
9220: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
9230: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
9240: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
9250: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
9260: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
9270: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
9280: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
9290: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
92a0: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
92b0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
92c0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n call..**.** ^T
92d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
92e0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
92f0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
9300: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
9310: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
9320: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
9330: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
9340: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
9350: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
9360: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
9370: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9380: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
9390: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
93a0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
93b0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
93c0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
93d0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
93e0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
93f0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
9400: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
9410: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
9420: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
9430: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
9440: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
9450: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
9460: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
9470: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
9480: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
9490: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
94a0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
94b0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
94c0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
94d0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
94e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
94f0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
9500: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
9510: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
9520: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
9530: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
9540: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
9550: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
9560: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
9570: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
9580: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
9590: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
95a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
95b0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
95c0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
95d0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
95e0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
95f0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
9600: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
9610: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
9620: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
9630: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
9640: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
9650: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
9660: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
9680: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
9690: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
96a0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
96b0: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
96c0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
96d0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
96e0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
96f0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
9700: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
9710: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
9720: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
9730: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
9740: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
9750: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
9760: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
9770: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
9780: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
9790: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
97a0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
97b0: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
97c0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
97d0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
97e0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
97f0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
9800: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
9810: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
9820: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
9830: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
9840: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
9850: 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36 34  multipled by 864
9860: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
9870: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
9880: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
9890: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
98a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
98b0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
98c0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
98d0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
98e0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
98f0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
9900: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
9910: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
9920: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
9930: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
9940: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
9950: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
9960: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
9970: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
9980: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
9990: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
99a0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
99b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
99c0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
99d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
99e0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
99f0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
9a00: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
9a10: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
9a20: 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e  ently 2) */.  in
9a30: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
9a40: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
9a50: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
9a60: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
9a70: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
9a80: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
9a90: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
9aa0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
9ab0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
9ac0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
9ad0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
9ae0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
9af0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
9b00: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
9b10: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
9b20: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
9b30: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
9b40: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
9b50: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
9b60: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
9b70: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
9b80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9b90: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
9ba0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
9bb0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
9bc0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9bd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9be0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9bf0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9c00: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
9c10: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
9c20: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
9c30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9c40: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
9c50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
9c60: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9c70: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9c80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9c90: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9ca0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9cb0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9cc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9cd0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9ce0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9cf0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9d00: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
9d10: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
9d20: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
9d30: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
9d40: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
9d50: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
9d60: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
9d70: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
9d80: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
9d90: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
9da0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9db0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9dc0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
9dd0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
9de0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
9df0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
9e00: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
9e10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
9e20: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
9e30: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
9e40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9e50: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
9e60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
9e70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
9e80: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
9e90: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9ea0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
9eb0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
9ec0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
9ed0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
9ee0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
9ef0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
9f00: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
9f10: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
9f20: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
9f30: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9f40: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
9f50: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
9f60: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9f70: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
9f80: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9f90: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
9fa0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
9fb0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
9fc0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
9fd0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
9fe0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
9ff0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a000: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
a010: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
a020: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a030: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
a040: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
a050: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
a060: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
a070: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
a080: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
a090: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
a0a0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
a0b0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
a0c0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
a0d0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
a0e0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
a0f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
a100: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
a110: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
a120: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
a130: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
a140: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
a150: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
a160: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
a170: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
a180: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
a190: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
a1a0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
a1b0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
a1c0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
a1d0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
a1e0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
a1f0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
a200: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
a210: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
a220: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a230: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
a240: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
a250: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
a260: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
a270: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
a280: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
a290: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
a2a0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
a2b0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
a2c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a2d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
a2e0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
a2f0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
a300: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
a310: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
a320: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
a330: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
a340: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
a350: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
a360: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
a370: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
a380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a390: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
a3a0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
a3c0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
a3d0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
a3e0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
a3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a400: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
a410: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
a420: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
a430: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
a440: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
a450: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
a460: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
a470: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
a480: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
a490: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
a4a0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
a4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
a4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a4d0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
a4e0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
a4f0: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
a500: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
a510: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
a520: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
a530: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
a540: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
a550: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a560: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a570: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
a580: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
a590: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
a5a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a5b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
a5c0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
a5d0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
a5e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a5f0: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
a600: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
a610: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
a620: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
a630: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
a640: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
a650: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
a660: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
a670: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
a680: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
a690: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
a6a0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
a6b0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
a6c0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
a6d0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
a6e0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
a6f0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
a700: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
a710: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
a720: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
a730: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
a740: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
a750: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
a760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
a770: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
a780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a790: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
a7a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a7b0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
a7c0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
a7d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
a7e0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
a7f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
a800: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
a810: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
a820: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
a830: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
a840: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
a850: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
a860: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
a870: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
a880: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
a890: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
a8a0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
a8b0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
a8c0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
a8d0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
a8e0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
a8f0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
a900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a910: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
a920: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
a930: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
a940: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
a950: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
a960: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
a970: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
a980: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
a990: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
a9a0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
a9b0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
a9c0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
a9d0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
a9e0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
a9f0: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
aa00: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
aa10: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
aa20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
aa30: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
aa40: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
aa50: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
aa60: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
aa70: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
aa80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
aa90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
aaa0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
aab0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
aac0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
aad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aae0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
aaf0: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
ab00: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
ab10: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
ab20: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ab30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ab40: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
ab50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
ab60: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ab70: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
ab80: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
ab90: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
aba0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
abb0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
abc0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
abd0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
abe0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
abf0: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
ac00: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
ac10: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
ac20: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ac30: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
ac40: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
ac50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
ac60: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
ac70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ac80: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
ac90: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
aca0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
acb0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
acc0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
acd0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
ace0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
acf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
ad00: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ad10: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
ad20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ad30: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
ad40: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
ad50: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
ad60: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
ad70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
ad80: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
ad90: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
ada0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
adb0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
adc0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
add0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
ade0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
adf0: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
ae00: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
ae10: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
ae20: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
ae30: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
ae40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
ae50: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
ae60: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ae70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ae80: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ae90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
aea0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
aeb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
aec0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
aed0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
aee0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
aef0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
af00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
af10: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
af20: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
af30: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
af40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
af50: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
af60: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
af70: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
af80: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
af90: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
afa0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
afb0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
afc0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
afd0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
afe0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
aff0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
b000: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
b010: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
b020: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
b030: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
b040: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
b050: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
b060: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
b070: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
b080: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
b090: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
b0a0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
b0b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
b0c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
b0d0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
b0e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
b0f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
b100: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
b110: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
b120: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
b130: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
b140: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
b150: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
b160: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
b170: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
b180: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b190: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
b1a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
b1b0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
b1c0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
b1d0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
b1e0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
b1f0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
b200: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
b210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
b220: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
b230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
b240: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
b250: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
b260: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
b270: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
b280: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
b290: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
b2a0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
b2b0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
b2c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
b2d0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
b2e0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
b2f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
b300: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
b310: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
b320: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
b330: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
b340: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
b350: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
b360: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
b370: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b380: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
b390: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
b3a0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
b3b0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
b3c0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
b3d0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
b3e0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
b3f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b400: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
b410: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
b420: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
b430: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
b440: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
b450: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b460: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
b470: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
b480: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
b490: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
b4a0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
b4b0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
b4c0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
b4d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
b4e0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
b4f0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
b500: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
b510: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
b520: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
b530: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
b540: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
b550: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
b560: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
b570: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
b580: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
b590: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
b5a0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b5b0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
b5c0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
b5d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
b5e0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b5f0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
b600: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
b610: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
b620: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
b630: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
b640: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
b650: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
b660: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
b670: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
b680: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
b690: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b6a0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
b6b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
b6c0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
b6d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
b6e0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
b6f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
b700: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
b710: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
b720: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
b730: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
b740: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
b750: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
b760: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
b770: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
b780: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
b790: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
b7a0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
b7b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
b7c0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
b7d0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
b7e0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b7f0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
b800: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
b810: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
b820: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
b830: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
b840: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
b850: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
b860: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b870: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
b880: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
b890: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
b8a0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
b8b0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
b8c0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
b8d0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
b8e0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
b8f0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
b900: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
b910: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b920: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
b930: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
b940: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
b950: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
b960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b970: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
b980: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
b990: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
b9a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
b9b0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
b9c0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
b9d0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
b9e0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
b9f0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
ba00: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
ba10: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
ba20: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ba30: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
ba40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
ba50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
ba60: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
ba70: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
ba80: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
ba90: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
baa0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
bab0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
bac0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
bad0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
bae0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
baf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bb00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
bb10: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
bb20: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
bb30: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
bb40: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
bb50: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
bb60: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
bb70: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
bb80: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
bb90: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
bba0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
bbb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bbc0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
bbd0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
bbe0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
bbf0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
bc00: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
bc10: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
bc20: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
bc30: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
bc40: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
bc50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
bc60: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
bc70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bc80: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
bc90: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
bca0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
bcb0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
bcc0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
bcd0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
bce0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bcf0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
bd00: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
bd10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bd20: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
bd30: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
bd40: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
bd50: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
bd60: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
bd70: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
bd80: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
bd90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
bda0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
bdb0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
bdc0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
bdd0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
bde0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
bdf0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
be00: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
be10: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
be20: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
be30: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
be40: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
be50: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
be60: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
be70: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
be80: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
be90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bea0: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
beb0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
bec0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
bed0: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
bee0: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
bef0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
bf00: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
bf10: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
bf20: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
bf30: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
bf40: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
bf50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
bf60: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
bf70: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
bf80: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
bf90: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
bfa0: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
bfb0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
bfc0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
bfd0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
bfe0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
bff0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c000: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
c010: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
c020: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
c030: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
c040: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
c050: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
c060: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
c070: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
c080: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
c090: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
c0a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
c0b0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
c0c0: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
c0d0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
c0e0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
c0f0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c100: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
c110: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c120: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
c130: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
c140: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
c150: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
c160: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
c170: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
c180: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
c190: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
c1a0: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
c1b0: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
c1c0: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
c1d0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
c1e0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
c1f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
c200: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
c210: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
c220: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
c230: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
c240: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c250: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
c260: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
c270: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
c280: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
c290: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
c2a0: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
c2b0: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
c2c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
c2d0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
c2e0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
c2f0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
c300: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
c310: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
c320: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
c330: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
c340: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
c350: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
c360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
c370: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
c380: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
c390: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c3a0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
c3b0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
c3c0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
c3d0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
c3e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c3f0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
c400: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
c410: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
c420: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
c430: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
c440: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
c450: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
c460: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
c470: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
c480: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
c490: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
c4a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c4b0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
c4c0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
c4d0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
c4e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
c4f0: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
c500: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c510: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
c520: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
c530: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
c540: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c550: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
c560: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
c570: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
c580: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
c590: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
c5a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c5b0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
c5c0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
c5d0: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
c5e0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
c5f0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
c600: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
c610: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
c620: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
c630: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
c640: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
c650: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
c660: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
c670: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
c680: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
c690: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
c6a0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
c6b0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
c6c0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c6d0: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
c6e0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
c6f0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
c700: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
c710: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
c720: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c730: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
c740: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
c750: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
c760: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
c770: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
c780: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
c790: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
c7a0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
c7b0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
c7c0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
c7d0: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
c7e0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
c7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
c800: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
c810: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
c820: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
c830: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
c840: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
c850: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
c860: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
c870: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
c880: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
c890: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
c8a0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
c8b0: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
c8c0: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
c8d0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
c8e0: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
c8f0: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
c900: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
c910: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
c920: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
c930: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
c940: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
c950: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
c960: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
c970: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
c980: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
c990: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
c9a0: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
c9b0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
c9c0: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
c9d0: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
c9e0: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
c9f0: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
ca00: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
ca10: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
ca20: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
ca30: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
ca40: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
ca50: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
ca60: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
ca70: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
ca80: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
ca90: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
caa0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
cab0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cac0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
cad0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
cae0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
caf0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
cb00: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
cb10: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
cb20: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
cb30: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
cb40: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
cb50: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
cb60: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
cb70: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
cb80: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
cb90: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
cba0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
cbb0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
cbc0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
cbd0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
cbe0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
cbf0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
cc00: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
cc10: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
cc20: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
cc30: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
cc40: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
cc50: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
cc60: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
cc70: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
cc80: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
cc90: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
cca0: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
ccb0: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
ccc0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
ccd0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
cce0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
ccf0: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
cd00: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
cd10: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
cd20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cd30: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
cd40: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
cd50: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
cd60: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
cd70: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
cd80: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
cd90: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
cda0: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
cdb0: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
cdc0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
cdd0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
cde0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
cdf0: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
ce00: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
ce10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ce20: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
ce30: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
ce40: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
ce50: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
ce60: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
ce70: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
ce80: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
ce90: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
cea0: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
ceb0: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
cec0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
ced0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
cee0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
cef0: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
cf00: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
cf10: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
cf20: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
cf30: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
cf40: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
cf50: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
cf60: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
cf70: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
cf80: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
cf90: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
cfa0: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
cfb0: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
cfc0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
cfd0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
cfe0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
cff0: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
d000: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
d010: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
d020: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d030: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
d040: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
d050: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
d060: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
d070: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
d080: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
d090: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
d0a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
d0b0: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
d0c0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
d0d0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
d0e0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
d0f0: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
d100: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
d110: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
d120: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
d130: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
d140: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
d150: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
d160: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
d170: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
d180: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
d190: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d1a0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
d1b0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
d1c0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
d1d0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
d1e0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
d1f0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
d200: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
d210: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
d220: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
d230: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
d240: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
d250: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
d260: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
d270: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
d280: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
d290: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
d2a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
d2b0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
d2c0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
d2d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
d2e0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
d2f0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
d300: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
d310: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
d320: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
d330: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
d340: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
d350: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
d360: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
d370: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
d380: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
d390: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
d3a0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
d3b0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
d3c0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
d3d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
d3e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
d3f0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
d400: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
d410: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
d420: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
d430: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
d440: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
d450: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
d460: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
d470: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
d480: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
d490: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
d4a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
d4b0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
d4c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d4d0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
d4e0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
d4f0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
d500: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
d510: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
d520: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
d530: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d540: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
d550: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
d560: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
d570: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
d580: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
d590: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d5a0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
d5b0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
d5c0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
d5d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d5e0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
d5f0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
d600: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
d610: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
d620: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
d630: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
d640: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
d650: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
d660: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
d670: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
d680: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
d690: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
d6a0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
d6b0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
d6c0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
d6d0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d6e0: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
d6f0: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
d700: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
d710: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
d720: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
d730: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
d740: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
d750: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
d760: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
d770: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
d780: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
d790: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
d7a0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
d7b0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
d7c0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d7d0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
d7e0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
d7f0: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
d800: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
d810: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
d820: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
d830: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
d840: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d850: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
d860: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
d870: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
d880: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d890: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
d8a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d8b0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d8c0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d8d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
d8e0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
d8f0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
d900: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
d910: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
d920: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
d930: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
d940: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
d950: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d960: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
d970: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
d980: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d990: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d9a0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d9b0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
d9c0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
d9d0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
d9e0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
d9f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da00: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
da10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
da20: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
da30: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
da40: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
da50: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
da60: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
da70: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
da80: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
da90: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
daa0: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
dab0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
dac0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
dad0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
dae0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
daf0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
db00: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
db10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
db20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
db30: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
db40: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
db50: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
db60: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
db70: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
db80: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
db90: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
dba0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
dbb0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
dbc0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
dbd0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
dbe0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
dbf0: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
dc00: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
dc10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
dc20: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
dc30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
dc40: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
dc50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
dc60: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
dc70: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
dc80: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
dc90: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
dca0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
dcb0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
dcc0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
dcd0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
dce0: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
dcf0: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
dd00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
dd10: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
dd20: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
dd30: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
dd40: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
dd50: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
dd60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
dd70: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
dd80: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
dd90: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dda0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
ddb0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
ddc0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
ddd0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dde0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ddf0: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
de00: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
de10: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
de20: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
de30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
de40: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
de50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
de60: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
de70: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
de80: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
de90: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dea0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
deb0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dec0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ded0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dee0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
def0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
df00: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
df10: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
df20: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
df30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
df40: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
df50: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
df60: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
df70: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
df80: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
df90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
dfa0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
dfb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
dfc0: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
dfd0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
dfe0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
dff0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
e000: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
e010: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
e020: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
e030: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
e040: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
e050: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
e060: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
e070: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
e080: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
e090: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
e0a0: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
e0b0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e0c0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
e0d0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
e0e0: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
e0f0: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
e100: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
e110: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
e120: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
e130: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
e140: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
e150: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e160: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
e170: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e180: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
e190: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
e1a0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
e1b0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e1c0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
e1d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
e1e0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
e1f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
e200: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
e210: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
e220: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
e230: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
e240: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
e250: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
e260: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
e270: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
e280: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
e2a0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
e2b0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
e2c0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
e2d0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
e2e0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
e2f0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
e300: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
e310: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
e320: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
e330: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
e340: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e350: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
e360: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e370: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
e380: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
e390: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
e3a0: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
e3b0: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
e3c0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
e3d0: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
e3e0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
e3f0: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
e400: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
e410: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
e420: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
e430: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
e440: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
e450: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
e460: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
e470: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
e480: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
e490: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
e4a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
e4b0: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
e4c0: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
e4d0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
e4e0: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
e4f0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
e500: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
e510: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
e520: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
e530: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
e540: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
e550: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
e560: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
e570: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
e580: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
e590: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
e5a0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
e5b0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
e5c0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
e5d0: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
e5e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e5f0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
e600: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e610: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
e620: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
e630: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
e640: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
e650: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
e660: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
e670: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
e680: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
e690: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
e6a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
e6b0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
e6c0: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
e6d0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
e6e0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
e6f0: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
e700: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
e710: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
e720: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
e730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
e740: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
e750: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
e760: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
e770: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
e780: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
e790: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
e7a0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
e7b0: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
e7c0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
e7d0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
e7e0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
e7f0: 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
e800: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
e810: 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
e820: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
e830: 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
e840: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
e850: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
e860: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e870: 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
e880: 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
e890: 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
e8a0: 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
e8b0: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
e8c0: 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
e8d0: 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
e8e0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
e8f0: 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
e900: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
e910: 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
e920: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
e930: 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
e940: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
e950: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e960: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
e970: 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
e980: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e990: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
e9a0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e9b0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e9c0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e9d0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e9e0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
e9f0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
ea00: 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
ea10: 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
ea20: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61   cache implemena
ea30: 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
ea40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
ea50: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
ea60: 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
ea70: 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
ea80: 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
ea90: 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
eaa0: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
eab0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
eac0: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
ead0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
eae0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
eaf0: 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
eb00: 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
eb10: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
eb20: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
eb30: 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
eb40: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
eb50: 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
eb60: 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
eb70: 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
eb80: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
eb90: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
eba0: 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
ebb0: 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
ebc0: 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
ebd0: 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
ebe0: 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
ebf0: 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
ec00: 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
ec10: 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
ec20: 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
ec30: 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
ec40: 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
ec50: 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
ec60: 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
ec70: 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
ec80: 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
ec90: 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
eca0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
ecb0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
ecc0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
ecd0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
ece0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
ecf0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
ed00: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
ed10: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
ed20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ed30: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
ed40: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
ed50: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
ed60: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
ed70: 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
ed80: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
ed90: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
eda0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
edb0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
edc0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
edd0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
ede0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
edf0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
ee00: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
ee10: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
ee20: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
ee30: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ee40: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
ee50: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
ee60: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
ee70: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
ee80: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
ee90: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
eea0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
eeb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
eec0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
eed0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
eee0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
eef0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
ef00: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
ef10: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
ef20: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
ef30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
ef40: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
ef50: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
ef60: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
ef70: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
ef80: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ef90: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
efa0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
efb0: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
efc0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
efd0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
efe0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
eff0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
f000: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
f010: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
f020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
f030: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
f040: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
f050: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
f060: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
f070: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
f080: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
f090: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
f0a0: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
f0b0: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
f0c0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
f0d0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
f0e0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
f0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f100: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
f110: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
f120: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
f130: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
f140: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
f150: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
f160: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
f170: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
f180: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
f190: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f1a0: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
f1b0: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
f1c0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
f1d0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
f1e0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
f1f0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f200: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
f210: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
f220: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
f230: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
f240: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
f250: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
f260: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
f270: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f280: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
f290: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f2a0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f2b0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f2c0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f2d0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
f2e0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
f2f0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f300: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
f310: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
f320: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
f330: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
f340: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
f350: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
f360: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
f370: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
f380: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
f390: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
f3a0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
f3b0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
f3c0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f3d0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
f3e0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
f3f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f400: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
f410: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f420: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f430: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f440: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f450: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f460: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f470: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
f480: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
f490: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
f4a0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
f4b0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
f4c0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f4d0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
f4e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f4f0: 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
f500: 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
f510: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
f520: 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
f530: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f540: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
f550: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f560: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f570: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f580: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f590: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f5a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f5b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
f5c0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
f5d0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
f5e0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f5f0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
f600: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
f610: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
f620: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
f630: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
f640: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
f650: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
f660: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
f670: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
f680: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
f690: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
f6a0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
f6b0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
f6c0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
f6d0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
f6e0: 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
f6f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f700: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f710: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f720: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f730: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f740: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f750: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
f760: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
f770: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
f780: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
f790: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
f7a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f7b0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f7c0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f7d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f7e0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
f7f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
f800: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
f810: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f820: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f830: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f840: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
f850: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
f860: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
f870: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
f880: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
f890: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
f8a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
f8b0: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
f8c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f8d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f8e0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
f8f0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
f900: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
f910: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
f920: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
f930: 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
f940: 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
f950: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
f960: 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
f970: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
f980: 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
f990: 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
f9a0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f9b0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
f9c0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
f9d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
f9e0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
f9f0: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
fa00: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
fa10: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
fa20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
fa30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fa40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
fa50: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
fa60: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
fa70: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
fa80: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
fa90: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
faa0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
fab0: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
fac0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
fad0: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
fae0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
faf0: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
fb00: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
fb10: 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
fb20: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
fb30: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
fb40: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
fb50: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
fb60: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
fb70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
fb80: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
fb90: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
fba0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
fbb0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
fbc0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
fbd0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
fbe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
fbf0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
fc00: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
fc10: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
fc20: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
fc30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
fc40: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
fc50: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
fc60: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fc70: 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
fc80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
fc90: 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
fca0: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
fcb0: 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
fcc0: 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
fcd0: 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
fce0: 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
fcf0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
fd00: 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
fd10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
fd20: 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
fd30: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fd40: 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
fd50: 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
fd60: 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
fd70: 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
fd80: 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
fd90: 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
fda0: 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
fdb0: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
fdc0: 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
fdd0: 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
fde0: 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
fdf0: 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
fe00: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fe10: 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
fe20: 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
fe30: 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
fe40: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
fe50: 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
fe60: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
fe70: 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
fe80: 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
fe90: 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
fea0: 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
feb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
fec0: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
fed0: 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
fee0: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
fef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
ff00: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
ff10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
ff20: 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
ff30: 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
ff40: 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
ff50: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
ff60: 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
ff70: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
ff80: 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
ff90: 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
ffa0: 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
ffb0: 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
ffc0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
ffd0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
ffe0: 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
fff0: 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
10000 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
10010 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
10020 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
10030 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
10040 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
10050 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
10060 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
10070 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
10080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10090 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
100a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
100b0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
100c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
100d0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
100e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
100f0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
10100 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10120 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
10130 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10150 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
10160 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10180 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
10190 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
101a0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
101b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
101c0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
101d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
101e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
101f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10200 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
10210 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
10220 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
10230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10240 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
10250 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
10260 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10280 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
10290 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
102a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
102b0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
102c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
102d0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
102e0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
102f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10300 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
10310 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
10320 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10340 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
10350 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
10360 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
10370 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
10380 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
10390 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
103a0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
103b0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
103c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
103d0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
103e0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
103f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10400 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
10410 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
10420 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
10430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10440 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
10450 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
10460 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
10470 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
10490 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
104a0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
104b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
104c0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
104d0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
104e0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
104f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10500 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10510 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10530 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
10550 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
10570 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10580 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
10590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
105a0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
105b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
105c0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
105d0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
105e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
105f0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
10600 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
10610 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
10620 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
10630 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
10640 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10650 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10660 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10670 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
10680 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10690 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
106a0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
106b0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
106c0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
106d0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
106e0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
106f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
10700 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
10710 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
10720 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10730 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
10740 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10750 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
10760 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
10770 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
10780 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
10790 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
107a0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
107b0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
107c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
107d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
107e0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
107f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10800 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
10810 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
10820 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
10830 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
10840 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
10850 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
10860 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10870 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
10880 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10890 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
108a0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
108b0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
108c0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
108d0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
108e0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
108f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10900 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
10910 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
10920 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
10930 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
10940 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
10950 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
10960 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10970 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
10980 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
10990 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
109a0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
109b0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
109c0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
109d0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
109e0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
109f0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
10a00 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
10a10 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
10a20 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
10a30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
10a40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
10a50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10a60 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
10a70 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
10a80 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
10a90 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
10aa0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
10ab0 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ler.** multiple 
10ac0 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a  of 8.  See also:
10ad0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10ae0 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a  LOOKASIDE]</dd>.
10af0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
10b00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
10b10 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10b20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
10b30 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a  d* int int */...
10b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10b50 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
10b60 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
10b70 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
10b80 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
10b90 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
10ba0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
10bb0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
10bc0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
10bd0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
10be0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
10bf0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
10c00 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
10c10 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
10c20 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
10c30 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
10c40 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
10c50 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10c60 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
10c70 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
10c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10c90 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
10ca0 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
10cb0 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
10cc0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
10cd0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
10ce0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
10cf0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
10d00 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
10d10 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
10d20 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
10d30 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
10d40 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
10d50 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
10d60 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
10d70 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
10d80 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
10d90 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
10da0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
10db0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
10dc0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
10dd0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
10de0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
10df0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
10e00 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
10e10 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
10e20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
10e30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
10e40 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
10e50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
10e60 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
10e70 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
10e80 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
10e90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10ea0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10eb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
10ec0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
10ed0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
10ee0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
10ef0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
10f00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
10f10 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
10f20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
10f30 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
10f40 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
10f50 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
10f60 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
10f70 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
10f80 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
10f90 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
10fa0 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
10fb0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
10fc0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
10fd0 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
10fe0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10ff0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
11000 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
11010 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
11020 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
11030 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29   trigger fired.)
11040 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
11050 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
11060 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
11070 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
11080 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
11090 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
110a0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
110b0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
110c0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
110d0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
110e0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
110f0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
11100 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
11110 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
11120 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
11130 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
11140 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
11150 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
11160 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
11170 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
11180 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
11190 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
111a0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
111b0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
111c0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
111d0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
111e0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
111f0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
11200 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
11210 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
11220 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
11230 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
11240 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
11250 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
11260 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
11270 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
11280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
11290 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
112a0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
112b0 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
112c0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
112d0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
112e0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
112f0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
11300 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
11310 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
11320 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
11330 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
11340 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
11350 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
11360 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
11370 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
11380 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
11390 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
113a0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
113b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
113c0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
113d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
113e0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
113f0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
11400 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
11410 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11420 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
11430 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11440 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
11450 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
11460 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
11470 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
11480 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
11490 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
114a0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
114b0 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
114c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
114d0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
114e0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
114f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11500 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
11510 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
11520 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
11530 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11540 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
11550 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
11560 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
11570 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
11580 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
11590 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
115a0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
115b0 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
115c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
115d0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
115e0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
115f0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
11600 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
11610 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
11620 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
11630 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
11640 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
11650 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
11660 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
11670 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
11680 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
11690 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
116a0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
116b0 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
116c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
116d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
116e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
116f0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
11700 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
11710 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
11720 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
11730 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
11740 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
11750 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
11760 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
11770 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
11780 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
11790 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
117a0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
117b0 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
117c0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
117d0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
117e0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
117f0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
11800 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
11810 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
11820 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
11830 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
11840 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
11850 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
11860 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
11870 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
11880 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
11890 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
118a0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
118b0 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
118c0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
118d0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
118e0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
118f0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
11900 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
11910 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
11920 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
11930 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
11940 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
11950 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
11960 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
11970 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
11980 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
11990 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
119a0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
119b0 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
119c0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
119d0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
119e0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
119f0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
11a00 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
11a10 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
11a20 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
11a30 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
11a40 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
11a50 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
11a60 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
11a70 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
11a80 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
11a90 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
11aa0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
11ab0 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
11ac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
11ad0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
11ae0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
11af0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
11b00 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
11b10 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11b20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
11b30 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11b40 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
11b50 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
11b60 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
11b70 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
11b80 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
11b90 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
11ba0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
11bb0 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
11bc0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
11bd0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
11be0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
11bf0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
11c00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
11c10 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
11c20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
11c30 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
11c40 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
11c50 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
11c60 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
11c70 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
11c80 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
11c90 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
11ca0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
11cb0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
11cc0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
11cd0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
11ce0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
11cf0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
11d00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
11d10 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
11d20 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
11d30 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
11d40 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
11d50 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11d60 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
11d70 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
11d80 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
11d90 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
11da0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
11db0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
11dc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11dd0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
11de0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
11df0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
11e00 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
11e10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
11e20 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
11e30 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
11e40 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
11e50 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11e60 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
11e70 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
11e80 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11e90 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11ea0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
11eb0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
11ec0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
11ed0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11ee0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
11ef0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11f00 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
11f10 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
11f20 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
11f30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11f40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11f50 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
11f60 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
11f70 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
11f80 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
11f90 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
11fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11fb0 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
11fc0 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
11fd0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
11fe0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
11ff0 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
12000 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
12010 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
12020 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
12030 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
12040 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
12050 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
12060 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
12070 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
12080 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
12090 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
120a0 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
120b0 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
120c0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
120d0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
120e0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
120f0 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
12100 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
12110 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
12120 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
12130 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
12140 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
12150 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
12160 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
12170 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
12180 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
12190 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
121a0 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
121b0 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
121c0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
121d0 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
121e0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
121f0 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
12200 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
12210 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
12220 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
12230 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
12240 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
12250 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
12260 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
12270 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
12280 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
12290 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
122a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
122b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
122c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
122d0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
122e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
122f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
12300 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
12310 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
12320 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
12330 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
12340 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
12350 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
12360 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
12370 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
12380 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
12390 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
123a0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
123b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
123c0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
123d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
123e0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
123f0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
12400 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
12410 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
12420 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
12430 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
12440 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
12450 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
12460 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
12470 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
12480 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
12490 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
124a0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
124b0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
124c0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
124d0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
124e0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
124f0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
12500 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
12510 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
12520 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
12530 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
12540 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
12550 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
12560 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
12570 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
12580 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
12590 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
125a0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
125b0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
125c0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
125d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
125e0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
125f0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
12600 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
12610 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12620 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
12630 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
12640 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
12650 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
12660 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
12670 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
12680 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
12690 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
126a0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
126b0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
126c0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
126d0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
126e0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
126f0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
12700 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
12710 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
12720 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
12730 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
12740 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
12750 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
12760 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
12770 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
12780 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
12790 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
127a0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
127b0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
127c0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
127d0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
127e0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
127f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
12800 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
12810 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
12820 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
12830 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
12840 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
12850 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12860 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
12870 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
12880 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
12890 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
128a0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
128b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
128c0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
128d0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
128e0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
128f0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
12900 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
12910 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
12920 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
12930 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12940 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
12950 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
12960 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
12970 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
12980 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
12990 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
129a0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
129b0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
129c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
129d0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
129e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
129f0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
12a00 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
12a10 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
12a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
12a30 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
12a40 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
12a50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
12a60 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
12a70 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
12a80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
12a90 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
12aa0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
12ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
12ac0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
12ad0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
12ae0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
12af0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
12b00 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
12b10 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
12b20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
12b30 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12b40 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
12b50 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
12b60 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
12b70 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
12b80 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
12b90 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
12ba0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
12bb0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
12bc0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
12bd0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
12be0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
12bf0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
12c00 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
12c10 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
12c20 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
12c30 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
12c40 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
12c50 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
12c60 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12c70 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
12c80 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
12c90 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
12ca0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
12cb0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
12cc0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
12cd0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
12ce0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
12cf0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
12d00 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
12d10 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
12d20 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
12d30 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
12d40 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
12d50 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
12d60 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
12d70 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
12d80 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
12d90 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
12da0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
12db0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
12dc0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
12dd0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
12de0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
12df0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
12e00 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
12e10 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
12e20 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
12e30 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
12e40 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
12e50 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
12e60 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
12e70 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
12e80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12e90 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
12ea0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
12eb0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
12ec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12ed0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
12ee0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
12ef0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
12f00 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
12f10 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
12f20 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
12f30 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
12f40 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
12f50 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
12f60 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
12f70 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
12f80 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
12f90 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
12fa0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
12fb0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
12fc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12fd0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
12fe0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12ff0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
13000 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
13010 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13020 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
13030 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
13040 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
13050 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
13060 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13070 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
13080 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
13090 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
130a0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
130b0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
130c0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
130d0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
130e0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
130f0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
13100 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
13110 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
13120 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
13130 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
13140 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
13150 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
13160 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
13170 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
13180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
13190 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
131a0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
131b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
131c0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
131d0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
131e0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
131f0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
13200 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
13210 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
13220 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
13230 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
13240 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
13250 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
13260 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
13270 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
13280 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
13290 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
132a0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
132b0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
132c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
132d0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
132e0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
132f0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
13300 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13310 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
13320 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
13330 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
13340 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
13350 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
13360 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
13370 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
13380 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
13390 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
133a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
133b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
133c0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
133d0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
133e0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
133f0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
13400 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
13410 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
13420 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
13430 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13440 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
13450 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
13460 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
13470 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
13480 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13490 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
134a0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
134b0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
134c0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
134d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
134e0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
134f0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
13500 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
13510 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
13520 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
13530 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13540 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
13550 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
13560 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
13570 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
13580 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
13590 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
135a0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
135b0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
135c0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
135d0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
135e0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
135f0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
13600 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
13610 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
13620 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
13630 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
13640 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
13650 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
13660 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
13670 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
13680 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
13690 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
136a0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
136b0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
136c0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
136d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
136e0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
136f0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
13700 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
13710 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
13720 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
13730 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
13740 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
13750 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
13760 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
13770 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
13780 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
13790 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
137a0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
137b0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
137c0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
137d0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
137e0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
137f0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
13800 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
13810 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
13820 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
13830 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
13840 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
13850 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
13860 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
13870 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
13880 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
13890 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
138a0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
138b0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
138c0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
138d0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
138e0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
138f0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
13900 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
13910 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
13920 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
13930 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
13940 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
13950 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
13960 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
13970 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
13980 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
13990 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
139a0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
139b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
139c0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
139d0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
139e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
139f0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
13a00 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
13a10 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
13a20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
13a30 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
13a40 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
13a50 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
13a60 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
13a70 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
13a80 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
13a90 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
13aa0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
13ab0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
13ac0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
13ad0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
13ae0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
13af0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
13b00 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
13b10 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
13b20 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
13b30 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
13b40 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
13b50 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
13b60 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
13b70 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
13b80 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
13b90 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
13ba0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
13bb0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
13bc0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
13bd0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
13be0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
13bf0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
13c00 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
13c10 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
13c20 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
13c30 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
13c40 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
13c50 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
13c60 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
13c70 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
13c80 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
13c90 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
13ca0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13cb0 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
13cc0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
13cd0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
13ce0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
13cf0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
13d00 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
13d10 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
13d20 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
13d30 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
13d40 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
13d50 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
13d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
13d70 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
13d80 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
13d90 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
13da0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
13db0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
13dc0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
13dd0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
13de0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
13df0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
13e00 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
13e10 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
13e20 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
13e30 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
13e40 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
13e50 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
13e60 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
13e70 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
13e80 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
13e90 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
13ea0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
13eb0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
13ec0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
13ed0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
13ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13ef0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
13f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13f10 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
13f20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13f30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13f40 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
13f50 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
13f60 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
13f70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13f80 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
13f90 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
13fa0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13fb0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
13fc0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
13fd0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
13fe0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
13ff0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
14000 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
14010 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
14020 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
14030 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
14040 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
14050 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
14060 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
14070 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
14080 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
14090 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
140a0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
140b0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
140c0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
140d0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
140e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
140f0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
14100 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
14110 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
14120 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
14130 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
14140 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
14150 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
14160 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
14170 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
14180 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
14190 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
141a0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
141b0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
141c0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
141d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
141e0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
141f0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
14200 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
14210 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
14220 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
14230 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
14240 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
14250 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
14260 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
14270 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
14280 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
14290 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
142a0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
142b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
142c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
142d0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
142e0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
142f0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
14300 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
14310 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
14320 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
14330 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
14340 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
14350 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14360 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
14370 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
14380 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
14390 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
143a0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
143b0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
143c0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
143d0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
143e0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
143f0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
14400 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
14410 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
14420 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
14430 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
14440 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
14450 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
14460 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
14470 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
14480 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
14490 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
144a0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
144b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
144c0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
144d0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
144e0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
144f0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
14500 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
14510 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
14520 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
14530 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
14540 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
14550 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
14560 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
14570 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
14580 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
14590 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
145a0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
145b0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
145c0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
145d0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
145e0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
145f0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
14600 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
14610 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
14620 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
14630 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
14640 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
14650 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
14660 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
14670 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
14680 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
14690 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
146a0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
146b0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
146c0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
146d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
146e0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
146f0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
14700 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
14710 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
14720 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
14730 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
14740 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14750 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
14760 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
14770 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
14780 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14790 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
147a0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
147b0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
147c0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
147d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
147e0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
147f0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
14800 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
14810 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
14820 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
14830 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14840 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
14850 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
14860 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
14870 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
14880 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
14890 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
148a0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
148b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
148c0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
148d0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
148e0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
148f0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
14900 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
14910 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14920 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
14930 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
14940 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
14950 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
14960 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
14970 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14980 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
14990 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
149a0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
149b0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
149c0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
149d0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
149e0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
149f0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
14a00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
14a10 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
14a20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a30 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
14a40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14a50 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te>.**.** ^The s
14a60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14a70 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
14a80 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
14a90 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
14aa0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
14ab0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
14ac0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14ad0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
14ae0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
14af0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
14b00 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
14b10 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
14b20 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
14b30 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
14b40 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
14b50 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
14b60 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
14b70 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
14b80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
14b90 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73  ** it should pas
14ba0 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
14bb0 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
14bc0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14bd0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14be0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14bf0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14c00 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14c10 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14c20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14c30 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14c40 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14c50 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14c60 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14c70 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14c80 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14c90 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14ca0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14cb0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14cc0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14cd0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14ce0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14cf0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
14d00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14d10 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
14d20 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
14d30 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
14d40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
14d50 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
14d60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14d70 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
14d80 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
14d90 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
14da0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
14db0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
14dc0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
14dd0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
14de0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
14df0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
14e00 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
14e10 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
14e20 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
14e30 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
14e40 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
14e50 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
14e60 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
14e70 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
14e80 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
14e90 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
14ea0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
14eb0 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  )].)^.*/.int sql
14ec0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
14ed0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
14ee0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
14ef0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
14f00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
14f10 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
14f20 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
14f30 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
14f40 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
14f50 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
14f60 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
14f70 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
14f80 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
14f90 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
14fa0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
14fb0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
14fc0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
14fd0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
14fe0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
14ff0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
15000 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
15010 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
15020 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
15030 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
15040 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
15050 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
15060 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
15070 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
15080 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15090 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
150a0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
150b0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
150c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
150d0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
150e0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
150f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
15100 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
15110 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
15120 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
15130 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
15140 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
15150 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
15160 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
15170 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
15180 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
15190 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
151a0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
151b0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
151c0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
151d0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
151e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
151f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15200 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
15210 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
15220 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
15230 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
15240 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
15250 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
15260 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
15270 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
15280 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
15290 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
152a0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
152b0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
152c0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
152d0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
152e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
152f0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
15300 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
15310 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15320 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
15330 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
15340 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
15350 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
15360 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
15370 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
15380 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
15390 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
153a0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
153b0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
153c0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
153d0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
153e0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
153f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
15400 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
15410 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
15420 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
15430 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
15440 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
15450 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
15460 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
15470 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
15480 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
15490 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
154a0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
154b0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
154c0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
154d0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
154e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
154f0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
15500 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
15510 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
15520 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
15530 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
15540 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
15550 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
15560 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
15570 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
15580 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
15590 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
155a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
155b0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
155c0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
155d0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
155e0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
155f0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
15600 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
15610 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
15620 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
15630 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
15640 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
15650 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
15660 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
15670 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
15680 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
15690 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
156a0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
156b0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
156c0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
156d0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
156e0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
156f0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
15700 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
15710 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
15720 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
15730 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
15740 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
15750 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
15760 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
15770 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
15780 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
15790 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
157a0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
157b0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
157c0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
157d0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
157e0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
157f0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
15800 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
15810 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
15820 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
15830 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
15840 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
15850 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
15860 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
15870 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
15880 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
15890 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
158a0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
158b0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
158c0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
158d0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
158e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
158f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15900 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
15910 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
15920 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
15930 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15940 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
15950 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
15960 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
15970 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15980 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15990 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
159a0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
159b0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
159c0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
159d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
159e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
159f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
15a00 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
15a10 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
15a20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15a30 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
15a40 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
15a50 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
15a60 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
15a70 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
15a80 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
15a90 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
15aa0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
15ab0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15ac0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
15ad0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
15ae0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
15af0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
15b00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15b10 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
15b20 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
15b30 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
15b40 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
15b50 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
15b60 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
15b70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15b80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
15b90 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15ba0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
15bb0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
15bc0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15bd0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
15be0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
15bf0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
15c00 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
15c10 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
15c20 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
15c30 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
15c40 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
15c50 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
15c60 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
15c70 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
15c80 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
15c90 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
15ca0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
15cb0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
15cc0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
15cd0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
15ce0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
15cf0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
15d00 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
15d10 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
15d20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
15d30 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
15d40 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
15d50 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
15d60 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
15d70 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
15d80 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
15d90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15da0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
15db0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
15dc0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
15dd0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
15de0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
15df0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
15e00 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
15e10 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
15e20 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
15e30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15e40 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
15e50 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
15e60 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
15e70 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
15e80 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
15e90 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
15ea0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
15eb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
15ec0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
15ed0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
15ee0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
15ef0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
15f00 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
15f10 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
15f20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
15f30 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
15f40 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
15f50 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
15f60 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
15f70 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
15f80 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
15f90 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
15fa0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
15fb0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
15fc0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
15fd0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
15fe0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
15ff0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
16000 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
16010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
16020 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
16030 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
16040 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
16050 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
16060 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
16070 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
16080 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
16090 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
160a0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
160b0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
160c0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
160d0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
160e0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
160f0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
16100 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
16110 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
16120 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
16130 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
16140 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
16150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16160 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16170 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16180 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16190 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
161a0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
161b0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
161c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
161d0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
161e0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
161f0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
16200 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
16210 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
16220 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16230 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
16240 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
16250 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
16260 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
16270 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
16280 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
16290 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
162a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
162b0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
162c0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
162d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
162e0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
162f0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
16300 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16310 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
16320 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
16330 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
16340 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
16350 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
16360 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
16370 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
16380 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16390 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
163a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
163b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
163c0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
163d0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
163e0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
163f0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
16400 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
16410 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
16420 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
16430 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
16440 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
16450 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
16460 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
16470 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
16480 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
16490 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
164a0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
164b0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
164c0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
164d0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
164e0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
164f0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
16500 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
16510 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
16520 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
16530 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
16540 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
16550 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
16560 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
16570 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
16580 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
16590 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
165a0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
165b0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
165c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
165d0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
165e0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
165f0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
16600 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
16610 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
16620 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
16630 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16640 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
16650 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
16660 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
16670 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
16680 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
16690 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
166a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
166b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
166c0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
166d0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
166e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
166f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
16700 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
16710 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
16720 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
16730 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
16740 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
16750 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
16760 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
16770 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16780 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
16790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
167a0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
167b0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
167c0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
167d0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
167e0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
167f0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
16800 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
16810 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
16820 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
16830 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16840 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
16850 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
16860 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16870 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
16880 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
16890 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
168a0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
168b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
168c0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
168d0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
168e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
168f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
16900 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
16910 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16920 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
16930 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
16940 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
16950 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16960 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
16970 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
16980 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
16990 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
169a0 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a  e boundary..**.*
169b0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
169c0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
169d0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
169e0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
169f0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
16a00 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
16a10 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
16a20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
16a30 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
16a40 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
16a50 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
16a60 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
16a70 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
16a80 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
16a90 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
16aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
16ab0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
16ac0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
16ad0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
16ae0 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
16af0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
16b00 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
16b10 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
16b20 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
16b30 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
16b40 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
16b50 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
16b60 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
16b70 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
16b80 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
16b90 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
16ba0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
16bb0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
16bc0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
16bd0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
16be0 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
16bf0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
16c00 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
16c10 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
16c20 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
16c30 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
16c40 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
16c50 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
16c60 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
16c70 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16c80 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
16c90 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
16ca0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
16cb0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
16cc0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
16cd0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
16ce0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
16cf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
16d00 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
16d10 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
16d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
16d30 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16d40 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
16d50 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
16d60 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
16d70 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
16d80 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
16d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
16da0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
16db0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
16dc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
16dd0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
16de0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
16df0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
16e00 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
16e10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
16e20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
16e30 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
16e40 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
16e50 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
16e60 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
16e70 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
16e80 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
16e90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
16ea0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
16eb0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
16ec0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16ed0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
16ee0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
16ef0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
16f00 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
16f10 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
16f20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16f30 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
16f40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16f50 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
16f60 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
16f70 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
16f80 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
16f90 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
16fa0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
16fb0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
16fc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
16fd0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
16fe0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
16ff0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
17000 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
17010 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
17020 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
17030 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
17040 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
17050 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
17060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
17070 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
17080 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
17090 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
170a0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
170b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
170c0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
170d0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
170e0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
170f0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
17100 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
17110 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
17120 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
17130 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
17140 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
17150 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
17160 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
17170 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
17180 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
17190 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
171a0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
171b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
171c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
171d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
171e0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
171f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
17200 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
17210 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
17220 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
17230 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
17240 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
17250 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
17260 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
17270 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
17280 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17290 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
172a0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
172b0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
172c0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
172d0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
172e0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
172f0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
17300 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
17310 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
17320 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
17330 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
17340 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
17350 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
17360 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
17370 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
17380 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
17390 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
173a0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
173b0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
173c0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
173d0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
173e0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
173f0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
17400 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
17410 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
17420 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
17430 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
17440 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
17450 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
17460 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
17470 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
17480 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
17490 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
174a0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
174b0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
174c0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
174d0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
174e0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
174f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
17500 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
17510 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
17520 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
17530 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
17540 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
17550 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
17560 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
17570 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
17580 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
17590 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
175a0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
175b0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
175c0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
175d0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
175e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
175f0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
17600 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
17610 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
17620 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
17630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17640 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
17650 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
17660 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
17670 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
17680 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
17690 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
176a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
176b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
176c0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
176d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
176e0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
176f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17700 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
17710 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
17720 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
17730 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
17740 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
17750 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
17760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17770 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
17780 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
17790 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
177a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
177b0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
177c0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
177d0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
177e0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
177f0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
17800 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
17810 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
17820 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17830 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
17840 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
17850 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
17860 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
17870 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17880 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
17890 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
178a0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
178b0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
178c0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
178d0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
178e0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
178f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17900 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
17910 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
17920 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
17930 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
17940 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
17950 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
17960 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
17970 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
17980 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17990 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
179a0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
179b0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
179c0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
179d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
179e0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
179f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17a00 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
17a10 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
17a20 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
17a30 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
17a40 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
17a50 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
17a60 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
17a70 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
17a80 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
17a90 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
17aa0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
17ab0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
17ac0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17ad0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
17ae0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
17af0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
17b00 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
17b10 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
17b20 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
17b30 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
17b40 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
17b50 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
17b60 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
17b70 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
17b80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17b90 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17ba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17bb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
17bc0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
17bd0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
17be0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17bf0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
17c00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17c10 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
17c20 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
17c30 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
17c40 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
17c50 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
17c60 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
17c70 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
17c80 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
17c90 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
17ca0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
17cb0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
17cc0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
17cd0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
17ce0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
17cf0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
17d00 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
17d10 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17d20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
17d30 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
17d40 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
17d50 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
17d60 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17d70 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
17d80 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
17d90 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
17da0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
17db0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
17dc0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
17dd0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
17de0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
17df0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
17e00 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
17e10 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
17e20 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
17e30 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
17e40 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
17e50 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
17e60 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
17e70 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
17e80 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
17e90 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
17ea0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
17eb0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
17ec0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
17ed0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17ee0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
17ef0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
17f00 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
17f10 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
17f20 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
17f30 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
17f40 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
17f50 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
17f60 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
17f70 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
17f80 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
17f90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17fa0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
17fb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17fc0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
17fd0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
17fe0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
17ff0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
18000 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
18010 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
18020 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
18030 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
18040 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
18050 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
18060 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
18070 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
18080 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
18090 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
180a0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
180b0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
180c0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
180d0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
180e0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
180f0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
18100 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18110 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
18120 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
18130 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
18140 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
18150 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
18160 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
18170 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
18180 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
18190 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
181a0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
181b0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
181c0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
181d0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
181e0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
181f0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
18200 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
18210 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
18220 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
18230 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
18240 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
18250 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
18260 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
18270 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
18280 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
18290 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
182a0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
182b0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
182c0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
182d0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
182e0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
182f0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
18300 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
18310 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
18320 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
18330 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
18340 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
18350 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
18360 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
18370 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
18380 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
18390 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
183a0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
183b0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
183c0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
183d0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
183e0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
183f0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
18400 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
18410 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
18420 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
18430 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
18440 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
18450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
18460 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
18470 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18480 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
18490 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
184a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
184b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
184c0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
184d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
184e0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
184f0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
18500 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
18510 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
18520 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
18530 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
18540 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
18550 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
18560 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
18570 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
18580 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
18590 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
185a0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
185b0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
185c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
185d0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
185e0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
185f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18600 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
18610 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
18620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
18630 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
18640 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18650 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18660 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
18670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18680 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
18690 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
186a0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
186b0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
186c0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
186d0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
186e0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
186f0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
18700 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
18710 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
18720 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
18730 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
18740 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
18750 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
18760 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
18770 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
18780 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
18790 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
187a0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
187b0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
187c0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
187d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
187e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
187f0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
18800 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
18810 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
18820 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
18830 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18840 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18850 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18860 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
18870 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
18880 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
18890 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
188a0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
188b0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
188c0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
188d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
188e0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
188f0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
18900 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18910 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
18920 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
18930 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
18940 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
18950 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
18960 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
18970 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
18980 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
18990 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
189a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
189b0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
189c0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
189d0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
189e0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
189f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
18a00 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
18a10 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
18a20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18a30 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
18a40 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
18a50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18a60 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
18a70 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
18a80 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
18a90 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
18aa0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
18ab0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18ac0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
18ad0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
18ae0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
18af0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
18b00 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
18b10 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
18b20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
18b30 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
18b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b50 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
18b60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
18b70 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
18b80 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
18b90 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
18ba0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
18bb0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
18bc0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
18bd0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
18be0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
18bf0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18c00 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
18c10 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
18c20 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
18c30 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
18c40 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18c50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18c60 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
18c70 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
18c80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18c90 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
18ca0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
18cb0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
18cc0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
18cd0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
18ce0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
18cf0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
18d00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
18d10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18d20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18d30 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18d40 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18d50 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
18d60 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
18d70 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
18d80 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
18d90 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
18da0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
18db0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
18dc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18dd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
18de0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
18df0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
18e00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e10 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
18e20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
18e30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18e40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e60 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
18e70 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
18e80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18e90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18eb0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
18ec0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
18ed0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18ee0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18f00 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
18f10 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
18f20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18f30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18f50 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
18f60 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
18f70 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18f80 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18fa0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
18fb0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
18fc0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18fd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18ff0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
19000 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
19010 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19020 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19030 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19040 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
19050 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
19060 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19070 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19080 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
19090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
190a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
190b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
190c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
190d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
190e0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
190f0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19100 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19110 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19120 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
19130 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
19140 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19150 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19160 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19170 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
19180 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
19190 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
191a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
191b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
191c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
191d0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
191e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
191f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19210 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
19220 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
19230 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19240 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19260 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
19270 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
19280 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19290 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
192a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
192b0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
192c0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
192d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
192e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
192f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19300 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
19310 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
19320 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
19330 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19350 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
19360 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
19370 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19380 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
193a0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
193b0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
193c0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
193d0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
193e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
193f0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
19400 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
19410 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
19420 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
19430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
19440 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
19450 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
19460 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
19470 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19480 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
19490 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
194a0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
194b0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
194c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
194d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
194e0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
194f0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
19500 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19510 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19520 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
19530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19540 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
19550 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19560 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19570 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
19580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
19590 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
195a0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
195b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
195c0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
195d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
195e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
195f0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
19600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19610 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
19620 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
19630 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19640 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19660 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
19670 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
19680 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19690 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
196a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
196b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
196c0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
196d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
196e0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
196f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19700 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
19710 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
19720 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19730 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19750 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
19760 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
19770 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19780 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
19790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
197a0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
197b0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
197c0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
197d0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
197e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
197f0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
19800 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
19810 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
19820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19830 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
19840 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
19850 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19860 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
19870 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19880 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
19890 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
198a0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
198b0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
198c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
198d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
198e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
198f0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19900 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
19910 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
19920 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
19930 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19940 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
19950 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19960 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
19970 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
19980 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
19990 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
199a0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
199b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
199c0 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
199d0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
199e0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
199f0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
19a00 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
19a10 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
19a20 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
19a30 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
19a40 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
19a50 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
19a60 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
19a70 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
19a80 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
19a90 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
19aa0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
19ab0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
19ac0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
19ad0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
19ae0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
19af0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
19b00 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19b10 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
19b20 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
19b30 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
19b40 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
19b50 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
19b60 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
19b70 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
19b80 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
19b90 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
19ba0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19bb0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
19bc0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
19bd0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
19be0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
19bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
19c00 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
19c10 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
19c20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
19c30 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
19c40 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
19c50 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
19c60 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
19c70 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
19c80 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
19c90 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
19ca0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
19cb0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
19cc0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
19cd0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19ce0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
19cf0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
19d00 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
19d10 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
19d20 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
19d30 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
19d40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
19d50 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
19d60 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
19d70 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
19d80 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
19d90 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
19da0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
19db0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
19dc0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
19dd0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
19de0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
19df0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
19e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
19e10 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
19e20 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
19e30 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
19e40 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
19e50 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
19e60 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
19e70 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
19e80 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
19e90 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
19ea0 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
19eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
19ec0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
19ed0 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
19ee0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19ef0 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
19f00 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
19f10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
19f20 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
19f30 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
19f40 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
19f50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
19f60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19f70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
19f80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
19f90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
19fa0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
19fb0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
19fc0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
19fd0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
19fe0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
19ff0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1a000 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a010 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
1a020 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1a030 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1a040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a050 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1a060 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1a070 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1a080 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1a090 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1a0a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1a0b0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1a0c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1a0d0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1a0e0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1a0f0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1a100 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1a110 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1a120 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1a130 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1a140 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1a150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a160 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1a170 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1a180 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1a190 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1a1a0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1a1b0 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
1a1c0 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
1a1d0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
1a1e0 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
1a1f0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1a200 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1a210 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
1a220 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1a230 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1a240 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
1a250 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1a260 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
1a270 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
1a280 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
1a290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1a2a0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
1a2b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
1a2c0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
1a2d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1a2e0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
1a2f0 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
1a300 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
1a310 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1a320 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1a330 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1a340 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
1a350 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
1a360 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1a370 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1a380 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1a390 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
1a3a0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1a3b0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1a3c0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1a3d0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1a3e0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1a3f0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1a400 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1a410 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
1a420 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
1a430 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
1a440 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1a450 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
1a460 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
1a470 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
1a480 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
1a490 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
1a4a0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
1a4b0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
1a4c0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1a4d0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
1a4e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1a4f0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1a500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1a510 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1a520 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a530 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1a540 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1a550 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1a560 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1a570 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1a580 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1a590 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1a5a0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1a5b0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1a5c0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1a5d0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1a5e0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1a5f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a600 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1a610 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1a620 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1a630 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1a640 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1a650 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1a660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a670 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1a680 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1a690 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1a6a0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1a6b0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1a6c0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1a6d0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1a6e0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1a6f0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1a700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a710 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
1a720 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
1a730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a740 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
1a750 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
1a760 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
1a770 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1a780 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
1a790 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1a7a0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1a7b0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1a7c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a7d0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61  AREDCACHE],.** a
1a7e0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1a7f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1a800 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1a810 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1a820 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1a830 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1a840 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a850 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1a860 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1a870 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a880 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1a890 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a8a0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a8b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1a8c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a8d0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1a8e0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1a8f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1a900 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1a910 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1a920 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1a930 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1a940 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1a950 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1a960 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1a970 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1a980 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1a990 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1a9a0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1a9b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1a9c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1a9d0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1a9e0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1a9f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1aa00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1aa10 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1aa20 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1aa30 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1aa40 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1aa50 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1aa60 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1aa70 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1aa80 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1aa90 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1aaa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1aab0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1aac0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
1aad0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1aae0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1aaf0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1ab00 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1ab10 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1ab20 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1ab30 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
1ab40 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1ab50 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
1ab60 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
1ab70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1ab80 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1ab90 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a  EN_FULLMUTEX],.*
1aba0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  * [SQLITE_OPEN_S
1abb0 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f  HAREDCACHE] and/
1abc0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1abd0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1abe0 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1abf0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1ac00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
1ac10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1ac20 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1ac30 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1ac40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ac50 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1ac60 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1ac70 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1ac80 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1ac90 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1aca0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1acb0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1acc0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1acd0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
1ace0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1acf0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1ad00 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
1ad10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ad20 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
1ad30 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1ad40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1ad50 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
1ad60 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
1ad70 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
1ad80 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
1ad90 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1ada0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1adb0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1adc0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1add0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ade0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
1adf0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
1ae00 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1ae10 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
1ae20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1ae30 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1ae40 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
1ae50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1ae60 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1ae70 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
1ae80 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1ae90 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
1aea0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1aeb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
1aec0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
1aed0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
1aee0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
1aef0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
1af00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1af10 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1af20 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1af30 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1af40 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1af50 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1af60 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1af70 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1af80 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1af90 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1afa0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1afb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1afc0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1afd0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1afe0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1aff0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1b000 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1b010 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1b020 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1b030 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1b040 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1b050 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1b060 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1b070 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1b080 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1b090 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1b0a0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1b0b0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1b0c0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1b0d0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1b0e0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1b0f0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1b100 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1b110 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1b120 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1b130 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1b140 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1b150 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1b160 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b170 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1b180 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1b190 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1b1a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1b1b0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   closed..**.** ^
1b1c0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1b1d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b1e0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1b1f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1b200 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1b210 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1b220 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1b230 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1b240 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1b250 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b260 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1b270 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1b280 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1b290 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1b2a0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1b2b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1b2c0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1b2d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
1b2e0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
1b2f0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
1b300 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
1b310 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1b320 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
1b330 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1b340 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
1b350 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
1b360 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
1b370 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
1b380 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
1b390 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
1b3a0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
1b3b0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
1b3c0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
1b3d0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
1b3e0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
1b3f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1b400 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1b410 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20  en_v2()..*/.int 
1b420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
1b430 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1b440 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1b450 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1b460 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1b470 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1b480 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1b490 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1b4a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1b4b0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
1b4c0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
1b4d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1b4e0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
1b4f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1b500 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1b510 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1b520 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1b530 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
1b540 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1b550 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1b560 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1b570 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1b580 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
1b590 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1b5a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
1b5b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
1b5c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
1b5d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1b5e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
1b5f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
1b600 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
1b610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b620 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
1b630 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
1b640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1b650 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
1b660 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1b670 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
1b680 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
1b690 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1b6a0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1b6b0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
1b6c0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
1b6d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1b6e0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1b6f0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
1b700 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
1b710 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
1b720 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
1b730 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
1b740 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1b750 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
1b760 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
1b770 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
1b780 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1b790 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
1b7a0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
1b7b0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
1b7c0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
1b7d0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
1b7e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1b7f0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
1b800 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1b810 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
1b820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b830 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1b840 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1b850 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1b860 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1b870 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1b880 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1b890 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1b8a0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1b8b0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
1b8c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1b8d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1b8e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1b8f0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1b900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1b910 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1b920 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1b930 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1b940 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1b950 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1b960 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1b970 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1b980 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1b990 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1b9a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1b9b0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
1b9c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
1b9d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1b9e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
1b9f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
1ba00 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
1ba10 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
1ba20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
1ba30 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
1ba40 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
1ba50 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
1ba60 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
1ba70 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
1ba80 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
1ba90 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
1baa0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
1bab0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
1bac0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
1bad0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
1bae0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
1baf0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
1bb00 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
1bb10 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
1bb20 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
1bb30 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
1bb40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bb50 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
1bb60 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1bb70 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
1bb80 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1bb90 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
1bba0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
1bbb0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
1bbc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
1bbd0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
1bbe0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
1bbf0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
1bc00 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
1bc10 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
1bc20 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
1bc30 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
1bc40 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
1bc50 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
1bc60 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
1bc70 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
1bc80 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
1bc90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bca0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
1bcb0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
1bcc0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
1bcd0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
1bce0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
1bcf0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1bd00 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1bd10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1bd20 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1bd30 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1bd40 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1bd50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1bd60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1bd70 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1bd80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1bd90 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1bda0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
1bdb0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1bdc0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1bdd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1bde0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1bdf0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1be00 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1be10 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1be20 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1be30 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1be40 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1be50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1be60 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1be70 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1be80 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1be90 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1bea0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1beb0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1bec0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1bed0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1bee0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1bef0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1bf00 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1bf10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1bf20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1bf30 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1bf40 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1bf50 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1bf60 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1bf70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1bf80 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1bf90 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1bfa0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1bfb0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1bfc0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1bfd0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1bfe0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1bff0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1c000 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1c010 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1c020 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1c030 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1c040 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1c050 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1c060 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1c070 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1c080 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1c090 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1c0a0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1c0b0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1c0c0 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1c0d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1c0e0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1c0f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1c100 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1c110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c120 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1c130 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
1c140 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1c150 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1c160 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1c170 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1c180 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1c190 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1c1a0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1c1b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1c1c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c1d0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1c1e0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1c1f0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1c200 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1c210 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1c220 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1c230 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1c240 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1c250 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1c260 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1c270 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1c280 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1c290 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1c2a0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1c2b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1c2c0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1c2d0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1c2e0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1c2f0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1c300 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1c310 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1c320 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1c330 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1c340 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1c350 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
1c360 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
1c370 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20  ound].** set by 
1c380 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
1c390 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1c3a0 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c  cro named .** [l
1c3b0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
1c3c0 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65  AX_XYZ]..** (The
1c3d0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1c3e0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1c3f0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
1c400 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
1c410 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
1c420 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
1c430 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
1c440 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
1c450 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
1c460 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
1c470 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1c480 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1c490 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1c4a0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1c4b0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1c4c0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1c4d0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1c4e0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1c4f0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1c500 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1c510 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1c520 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1c530 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1c540 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1c550 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1c560 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1c570 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1c580 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1c590 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1c5a0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1c5b0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1c5c0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1c5d0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1c5e0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1c5f0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1c600 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1c610 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1c620 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1c630 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1c640 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1c650 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1c660 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1c670 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1c680 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1c690 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1c6a0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1c6b0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1c6c0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1c6d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1c6e0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1c6f0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1c700 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1c710 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1c720 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1c730 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1c740 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1c750 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1c760 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1c770 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1c780 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1c790 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1c7a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1c7b0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1c7c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1c7d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c7e0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1c7f0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1c800 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1c810 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1c820 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
1c830 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
1c840 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
1c850 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1c860 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1c870 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1c880 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
1c890 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
1c8a0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
1c8b0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
1c8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1c8d0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
1c8e0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
1c8f0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
1c900 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
1c910 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
1c920 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1c930 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
1c940 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
1c950 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
1c960 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
1c970 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c980 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1c990 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c9a0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1c9b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1c9c0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29   table row.<dd>)
1c9d0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1c9f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1ca00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1ca10 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
1ca20 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
1ca30 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
1ca40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1ca50 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
1ca60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1ca70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1ca80 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
1ca90 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
1caa0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
1cab0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
1cac0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
1cad0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1cae0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
1caf0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
1cb00 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
1cb10 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
1cb20 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cb30 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1cb40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1cb50 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1cb60 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
1cb70 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
1cb80 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
1cb90 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1cba0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1cbb0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
1cbc0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cbd0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
1cbe0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
1cbf0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
1cc00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1cc10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1cc20 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
1cc30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cc40 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
1cc50 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
1cc60 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
1cc70 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
1cc80 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
1cc90 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
1cca0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1ccb0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1ccc0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1ccd0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cce0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1ccf0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1cd00 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1cd10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1cd20 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1cd30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1cd40 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
1cd50 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
1cd60 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
1cd70 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1cd80 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1cd90 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1cda0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1cdb0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1cdc0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1cdd0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
1cde0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
1cdf0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
1ce00 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1ce10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ce20 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1ce30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1ce40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1ce50 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1ce60 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1ce70 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1ce80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1ce90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1cea0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
1ceb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1cec0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1ced0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
1cee0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
1cef0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1cf00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cf10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1cf20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1cf30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1cf40 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1cf50 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1cf60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1cf70 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1cf80 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1cf90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1cfa0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1cfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1cfc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1cfd0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1cfe0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1cff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d000 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1d010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1d020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d030 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1d040 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1d050 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1d060 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1d070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d080 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1d090 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1d0a0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1d0b0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1d0c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1d0d0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1d0e0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
1d0f0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1d100 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1d110 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
1d120 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1d130 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1d140 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1d150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1d160 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
1d170 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
1d180 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
1d190 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
1d1a0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
1d1b0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
1d1c0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
1d1d0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1d1e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1d1f0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
1d200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d210 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
1d220 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
1d230 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1d240 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1d250 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1d260 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
1d270 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1d280 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
1d290 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
1d2a0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
1d2b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
1d2c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1d2d0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1d2e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1d2f0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1d300 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1d310 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1d320 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1d330 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1d340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1d350 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1d360 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1d370 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1d380 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d390 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1d3a0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1d3b0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
1d3c0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1d3d0 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1d3e0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1d3f0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1d400 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1d410 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
1d420 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1d430 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1d440 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
1d450 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1d460 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
1d470 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1d480 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1d490 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1d4a0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1d4b0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1d4c0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1d4d0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1d4e0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1d4f0 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1d500 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1d510 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1d520 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1d530 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1d540 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1d550 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1d560 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1d570 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1d580 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1d590 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1d5a0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1d5b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1d5c0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1d5d0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1d5e0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1d5f0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1d600 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  es..**.** ^If pz
1d610 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1d620 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1d630 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1d640 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1d650 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
1d660 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1d670 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1d680 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1d690 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
1d6a0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
1d6b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1d6c0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1d6d0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1d6e0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
1d6f0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1d700 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
1d710 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1d720 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1d730 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d740 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1d750 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1d760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1d770 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
1d780 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1d790 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1d7a0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
1d7b0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1d7c0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1d7d0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
1d7e0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
1d7f0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1d800 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1d810 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
1d820 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1d830 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1d840 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1d850 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1d860 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1d870 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d880 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1d890 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1d8a0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
1d8b0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
1d8c0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
1d8d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
1d8e0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
1d8f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
1d910 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
1d920 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1d930 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1d940 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1d950 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
1d960 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1d970 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
1d980 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
1d990 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
1d9a0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
1d9b0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
1d9c0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
1d9d0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1d9e0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
1d9f0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
1da00 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
1da10 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1da20 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1da30 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1da40 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1da50 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1da60 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1da70 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1da80 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
1da90 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
1daa0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1dab0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1dac0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1dad0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
1dae0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
1daf0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1db00 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
1db10 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1db20 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1db30 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1db40 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1db50 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1db60 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1db70 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1db80 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1db90 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1dba0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1dbb0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1dbc0 20 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61    ^If the schema
1dbd0 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a   has changed in.
1dbe0 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61  ** a way that ma
1dbf0 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e  kes the statemen
1dc00 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69  t no longer vali
1dc10 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  d, [sqlite3_step
1dc20 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a  ()] will still.*
1dc30 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1dc40 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75  _SCHEMA].  But u
1dc50 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79  nlike the legacy
1dc60 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49   behavior, [SQLI
1dc70 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a  TE_SCHEMA] is.**
1dc80 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72   now a fatal err
1dc90 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71  or.  Calling [sq
1dca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dcb0 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e  ()] again will n
1dcc0 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65  ot make the.** e
1dcd0 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e  rror go away.  N
1dce0 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65  ote: use [sqlite
1dcf0 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66  3_errmsg()] to f
1dd00 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20  ind the text.** 
1dd10 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65  of the parsing e
1dd20 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74  rror that result
1dd30 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  s in an [SQLITE_
1dd40 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a  SCHEMA] return..
1dd50 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1dd60 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
1dd70 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1dd80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1dd90 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1dda0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1ddb0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1ddc0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1ddd0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
1dde0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1ddf0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1de00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1de10 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1de20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1de30 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1de40 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
1de50 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
1de60 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1de70 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1de80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1de90 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
1dea0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1deb0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1dec0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1ded0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1dee0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1def0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1df00 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1df10 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1df20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1df30 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1df40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
1df50 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65  e of a [paramete
1df60 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1df70 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45  er] in the WHERE
1df80 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a   clause might.**
1df90 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72   change the quer
1dfa0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
1dfb0 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  tement, then the
1dfc0 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62   statement may b
1dfd0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1dfe0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61  ly recompiled (a
1dff0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
1e000 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61  een a schema cha
1e010 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73  nge) on the firs
1e020 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  t .** [sqlite3_s
1e030 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1e040 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1e050 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
1e060 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1e070 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
1e080 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  e [parameter]. .
1e090 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1e0a0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1e0b0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1e0c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e0d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1e0e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e0f0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1e100 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1e110 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1e120 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1e130 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1e140 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1e150 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1e160 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1e170 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1e180 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1e190 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1e1a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1e1b0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1e1c0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1e1d0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1e1e0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1e1f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1e200 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1e210 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1e220 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1e230 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1e240 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1e250 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1e260 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1e270 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1e280 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1e290 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1e2a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1e2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1e2c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1e2d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1e2e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1e2f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1e300 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1e310 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1e320 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1e330 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1e340 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1e350 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1e360 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1e370 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1e380 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1e390 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1e3a0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1e3b0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1e3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1e3d0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1e3e0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1e3f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1e400 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e410 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e420 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e430 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1e440 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e450 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e460 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e470 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e480 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1e490 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e4a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1e4b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1e4c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1e4d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1e4e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1e4f0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1e500 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1e510 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1e520 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1e530 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1e540 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1e550 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1e560 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1e570 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1e580 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1e590 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1e5a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1e5b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1e5c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1e5d0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1e5e0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1e5f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1e600 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1e610 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1e620 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1e630 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1e640 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1e650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e660 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1e670 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1e680 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1e690 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1e6a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1e6b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e6c0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1e6d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1e6e0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1e6f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1e700 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1e710 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1e720 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1e730 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1e740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1e750 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1e760 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1e770 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1e780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e790 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1e7a0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1e7b0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1e7c0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1e7d0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
1e7e0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1e7f0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
1e800 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1e810 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
1e820 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1e830 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1e840 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1e850 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1e860 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1e870 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1e880 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1e890 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1e8a0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1e8b0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1e8c0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1e8d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1e8e0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1e8f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1e900 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1e910 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1e920 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1e930 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1e940 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1e950 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1e960 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1e970 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1e980 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1e990 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1e9a0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1e9b0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1e9c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1e9d0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1e9e0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1e9f0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1ea00 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1ea10 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1ea20 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1ea30 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1ea40 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1ea50 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1ea60 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1ea70 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1ea80 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1ea90 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1eaa0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1eab0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1eac0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1ead0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1eae0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1eaf0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1eb00 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1eb10 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1eb20 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1eb30 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1eb40 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1eb50 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1eb60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1eb70 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1eb80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1eb90 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1eba0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1ebb0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1ebc0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1ebd0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1ebe0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ebf0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1ec00 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1ec10 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1ec20 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1ec30 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1ec40 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1ec50 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1ec60 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1ec70 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1ec80 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1ec90 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1eca0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ecb0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ecc0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1ecd0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1ece0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ecf0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ed00 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1ed10 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1ed20 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1ed30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1ed40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ed50 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ed60 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1ed70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1ed80 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1ed90 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1eda0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1edb0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1edc0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1edd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ede0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1edf0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1ee00 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1ee10 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1ee20 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1ee30 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1ee40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1ee50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1ee60 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1ee70 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1ee80 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1ee90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1eea0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1eeb0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1eec0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1eed0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1eee0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1eef0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
1ef00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1ef10 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1ef20 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1ef30 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1ef40 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1ef50 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1ef60 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
1ef70 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ef80 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
1ef90 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1efa0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
1efb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1efc0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
1efd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
1efe0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1eff0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
1f000 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
1f010 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
1f020 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
1f030 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1f040 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1f050 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1f060 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1f070 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
1f080 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1f090 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1f0a0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1f0b0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
1f0c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
1f0d0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
1f0e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1f0f0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1f100 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1f110 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1f120 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1f130 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
1f140 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1f150 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
1f160 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1f170 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1f180 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1f190 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f1a0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1f1b0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1f1c0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1f1d0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
1f1e0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
1f1f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f200 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
1f210 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f220 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
1f230 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
1f240 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1f250 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
1f260 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
1f270 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
1f280 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
1f290 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1f2a0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1f2b0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1f2c0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1f2d0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1f2e0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1f2f0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
1f300 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
1f310 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
1f320 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
1f330 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
1f340 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
1f350 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
1f360 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
1f370 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
1f380 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
1f390 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
1f3a0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
1f3b0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1f3c0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1f3d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f3e0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1f3f0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1f400 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1f410 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1f420 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1f430 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1f440 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1f450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1f460 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1f470 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1f480 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f490 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1f4a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
1f4b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1f4c0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1f4d0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1f4e0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
1f4f0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
1f500 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1f510 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
1f520 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
1f530 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
1f540 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
1f550 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
1f560 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
1f570 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
1f580 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
1f590 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
1f5a0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
1f5b0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
1f5c0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
1f5d0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
1f5e0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
1f5f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1f600 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1f610 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
1f620 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
1f630 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
1f640 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
1f650 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
1f660 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1f670 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1f680 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
1f690 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
1f6a0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
1f6b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1f6c0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
1f6d0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
1f6e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
1f6f0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1f700 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1f710 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1f720 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
1f730 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
1f740 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
1f750 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
1f760 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1f770 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
1f780 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
1f790 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
1f7a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f7b0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
1f7c0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
1f7d0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
1f7e0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
1f7f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
1f800 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
1f810 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
1f820 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
1f830 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
1f840 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
1f850 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1f860 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1f870 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
1f880 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f890 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1f8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f8b0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1f8c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1f8d0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1f8e0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1f8f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1f900 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1f910 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1f920 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66  hed with it. ^If
1f930 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1f940 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1f950 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1f960 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1f970 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1f980 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1f990 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1f9a0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1f9b0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1f9c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1f9d0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
1f9e0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1f9f0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1fa00 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1fa10 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1fa20 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1fa30 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1fa40 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1fa50 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1fa60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1fa70 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1fa80 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
1fa90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1faa0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1fab0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1fac0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1fad0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1fae0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
1faf0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
1fb00 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
1fb10 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
1fb20 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
1fb30 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
1fb40 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1fb50 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1fb60 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1fb70 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1fb80 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1fb90 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1fba0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1fbb0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
1fbc0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
1fbd0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
1fbe0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
1fbf0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
1fc00 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
1fc10 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1fc20 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1fc30 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
1fc40 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
1fc50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1fc60 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fc70 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1fc80 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
1fc90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fca0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
1fcb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fcc0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
1fcd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fce0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
1fcf0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
1fd00 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
1fd10 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
1fd20 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
1fd30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
1fd40 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
1fd50 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
1fd60 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
1fd70 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
1fd80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
1fd90 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
1fda0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
1fdb0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1fdc0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
1fdd0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
1fde0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
1fdf0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1fe00 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
1fe10 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
1fe20 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1fe30 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1fe40 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
1fe50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
1fe60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1fe70 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1fe80 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
1fe90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
1fea0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1feb0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
1fec0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
1fed0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
1fee0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
1fef0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
1ff00 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
1ff10 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
1ff20 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
1ff30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1ff40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff50 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1ff60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ff70 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1ff80 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1ff90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ffa0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1ffb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1ffc0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
1ffd0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1ffe0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
1fff0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
20000 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
20010 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
20020 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
20030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20040 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
20050 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
20060 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20070 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
20080 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
20090 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
200a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
200b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
200c0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
200d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
200e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
200f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
20100 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
20110 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
20120 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
20130 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20140 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
20150 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
20160 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
20170 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
20180 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
20190 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
201a0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
201b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
201c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
201d0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
201e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
201f0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
20200 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
20210 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
20220 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
20230 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
20240 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
20250 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
20260 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
20270 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
20280 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
20290 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
202a0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
202b0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
202c0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
202d0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
202e0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
202f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20300 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
20310 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
20320 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
20330 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
20340 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
20350 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
20360 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
20370 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
20380 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
20390 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
203a0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
203b0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
203c0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
203d0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
203e0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
203f0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
20400 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
20410 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
20420 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
20430 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
20440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20450 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
20460 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
20470 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20480 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
20490 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
204a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
204b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
204c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
204d0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
204e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
204f0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
20500 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
20510 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20520 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
20530 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
20540 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
20550 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
20560 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
20570 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
20580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
20590 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
205a0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
205b0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
205c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
205d0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
205e0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
205f0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
20600 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
20610 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
20620 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
20630 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
20640 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
20650 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
20660 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
20670 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
20680 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
20690 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
206a0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
206b0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
206c0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
206d0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
206e0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
206f0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
20700 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
20710 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
20720 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
20730 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
20740 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
20750 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
20760 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
20770 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
20780 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
20790 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
207a0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
207b0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
207c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
207d0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
207e0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
207f0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
20800 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
20810 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
20820 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
20830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20840 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
20850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20860 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
20870 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
20880 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
20890 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
208a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
208b0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
208c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
208d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
208e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
208f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
20900 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
20910 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
20920 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
20930 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
20940 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
20950 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
20960 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
20970 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
20980 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
20990 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
209a0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
209b0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
209c0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
209d0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
209e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
209f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
20a00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
20a10 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
20a20 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
20a30 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
20a40 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
20a50 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
20a60 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
20a70 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
20a80 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
20a90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
20aa0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
20ab0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
20ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20ad0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
20ae0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
20af0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
20b00 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
20b10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20b20 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
20b30 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
20b40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20b50 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
20b60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20b70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
20b80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
20b90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
20ba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20bb0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
20bc0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
20bd0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
20be0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
20bf0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
20c00 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
20c10 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
20c20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
20c30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20c40 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
20c50 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
20c60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
20c70 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
20c80 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
20c90 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
20ca0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
20cb0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
20cc0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
20cd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20ce0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
20cf0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
20d00 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
20d10 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
20d20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
20d30 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
20d40 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
20d50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20d60 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
20d70 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
20d80 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
20d90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
20da0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
20db0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
20dc0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
20dd0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
20de0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
20df0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
20e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20e10 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
20e20 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
20e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
20e40 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
20e50 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
20e60 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
20e70 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
20e80 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
20e90 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
20ea0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
20eb0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
20ec0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
20ed0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
20ee0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
20ef0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
20f00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
20f10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
20f20 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
20f30 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
20f40 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
20f50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
20f60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
20f70 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
20f80 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
20f90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
20fa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20fb0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
20fc0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
20fd0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
20fe0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
20ff0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
21000 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
21010 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
21020 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
21030 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
21040 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
21050 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
21060 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
21070 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21080 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
21090 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
210a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
210b0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
210c0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
210d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
210e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
210f0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
21100 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
21110 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
21120 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
21130 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
21140 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
21150 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
21160 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
21170 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
21180 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
21190 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
211a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
211b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
211c0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
211d0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
211e0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
211f0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
21200 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
21210 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
21220 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
21230 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
21240 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
21250 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
21260 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
21270 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
21280 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
21290 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
212a0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
212b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
212c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
212d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
212e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
212f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
21300 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
21310 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
21320 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
21330 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
21340 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
21350 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
21360 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
21370 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
21380 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
21390 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
213a0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
213b0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
213c0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
213d0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
213e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
213f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
21400 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
21410 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
21420 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
21430 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
21440 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
21450 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
21460 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
21470 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
21480 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
21490 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
214a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
214b0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
214c0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
214d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
214e0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
214f0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
21500 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
21510 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
21520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21530 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
21540 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
21550 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
21560 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
21570 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
21580 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
21590 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
215a0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
215b0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
215c0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
215d0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
215e0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
215f0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
21600 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
21610 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
21620 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
21630 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
21640 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21650 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
21660 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
21670 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
21680 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
21690 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
216a0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
216b0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
216c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
216d0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
216e0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
216f0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
21700 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
21710 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
21720 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
21730 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
21740 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
21750 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
21760 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
21770 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
21780 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
21790 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
217a0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
217b0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
217c0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
217d0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
217e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
217f0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
21800 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
21810 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
21820 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
21830 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
21840 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
21850 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
21860 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
21870 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
21880 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
21890 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
218a0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
218b0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
218c0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
218d0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
218e0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
218f0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
21900 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
21910 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
21920 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
21930 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
21940 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
21950 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
21960 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
21970 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
21980 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
21990 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
219a0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
219b0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
219c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
219d0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
219e0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
219f0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
21a00 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
21a10 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
21a20 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
21a30 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
21a40 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
21a50 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
21a60 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
21a70 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
21a80 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
21a90 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
21aa0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
21ab0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
21ac0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
21ad0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
21ae0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
21af0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
21b00 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
21b10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
21b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
21b30 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
21b40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21b50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21b60 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
21b70 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
21b80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21b90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21ba0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
21bb0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
21bc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
21bd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21be0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
21bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21c00 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
21c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
21c20 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
21c30 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21c40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21c50 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
21c60 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
21c70 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
21c80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
21c90 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
21ca0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
21cb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
21cc0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
21cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21ce0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
21cf0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
21d00 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
21d10 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
21d20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
21d30 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
21d40 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
21d50 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
21d60 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
21d70 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
21d80 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
21d90 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
21da0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
21db0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
21dc0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
21dd0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
21de0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
21df0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
21e00 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
21e10 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
21e20 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
21e30 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
21e40 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
21e50 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
21e60 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
21e70 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
21e80 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
21e90 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
21ea0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
21eb0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
21ec0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
21ed0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
21ee0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
21ef0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
21f00 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
21f10 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
21f20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
21f30 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
21f40 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
21f50 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
21f60 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
21f70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
21f80 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
21f90 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
21fa0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
21fb0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
21fc0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
21fd0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
21fe0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
21ff0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
22000 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
22010 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
22020 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
22030 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
22040 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
22050 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
22060 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
22070 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
22080 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
22090 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
220a0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
220b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
220c0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
220d0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
220e0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
220f0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
22100 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
22110 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22120 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
22130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
22140 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
22150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
22160 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
22170 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
22180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
22190 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
221a0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
221b0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
221c0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
221d0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
221e0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
221f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22200 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22210 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
22220 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
22230 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
22240 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
22250 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
22260 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
22270 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
22280 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
22290 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
222a0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
222b0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
222c0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
222d0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
222e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
222f0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
22300 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
22310 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
22320 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
22330 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
22340 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
22350 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22360 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
22370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22380 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
22390 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
223a0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
223b0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
223c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
223d0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
223e0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
223f0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
22400 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
22410 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
22420 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
22430 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
22440 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
22450 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
22460 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
22470 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
22480 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
22490 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
224a0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
224b0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
224c0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
224d0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
224e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
224f0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
22500 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
22510 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
22520 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
22530 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
22540 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
22550 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
22560 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
22570 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
22580 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
22590 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
225a0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
225b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
225c0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
225d0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
225e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
225f0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
22600 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
22610 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
22620 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
22630 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
22640 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
22650 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
22660 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
22670 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
22680 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
22690 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
226a0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
226b0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
226c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
226d0 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
226e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
226f0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
22700 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
22710 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
22720 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
22730 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
22740 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
22750 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
22760 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
22770 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
22780 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
22790 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
227a0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
227b0 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
227c0 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
227d0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
227e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
227f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
22800 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
22810 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
22820 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
22830 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
22840 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
22850 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
22860 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
22870 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
22880 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
22890 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
228a0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
228b0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
228c0 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
228d0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
228e0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
228f0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
22900 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
22910 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
22920 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
22930 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
22940 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
22950 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
22960 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
22970 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
22980 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
22990 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
229a0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
229b0 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
229c0 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
229d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
229e0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
229f0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
22a00 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
22a10 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
22a20 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
22a30 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
22a40 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
22a50 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
22a60 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
22a70 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
22a80 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
22a90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22aa0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
22ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22ac0 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
22ad0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
22ae0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
22af0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
22b00 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
22b10 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
22b20 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
22b30 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
22b40 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
22b50 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
22b60 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
22b70 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
22b80 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
22b90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22ba0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
22bb0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
22bc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
22bd0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
22be0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
22bf0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
22c00 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
22c10 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
22c20 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
22c30 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
22c40 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
22c50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22c60 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
22c70 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
22c80 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
22c90 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
22ca0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
22cb0 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
22cc0 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
22cd0 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
22ce0 2e 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20  .6.23.1, it was 
22cf0 72 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65  required.** afte
22d00 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
22d10 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
22d20 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
22d30 51 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a  QLITE_ROW] that.
22d40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
22d50 74 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62  t()] be called b
22d60 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
22d70 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
22d80 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
22d90 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
22da0 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  o invoke [sqlite
22db0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68  3_reset()] in th
22dc0 69 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20  is way would.** 
22dd0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
22de0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
22df0 75 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  urn from sqlite3
22e00 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
22e10 74 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33  ter.** version 3
22e20 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
22e30 5f 73 74 65 70 28 29 20 62 65 67 61 6e 20 63 61  _step() began ca
22e40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
22e50 65 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f  eset()] .** auto
22e60 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
22e70 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
22e80 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
22e90 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
22ea0 55 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62  USE].  .**.** <b
22eb0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
22ec0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
22ed0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
22ee0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
22ef0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
22f00 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
22f10 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
22f20 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
22f30 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
22f40 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
22f50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
22f60 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
22f70 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
22f80 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
22f90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
22fa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22fb0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
22fc0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
22fd0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
22fe0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
22ff0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
23000 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
23010 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
23020 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
23030 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
23040 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
23050 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
23060 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
23070 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
23080 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
23090 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
230a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
230b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
230c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
230d0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
230e0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
230f0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
23100 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
23110 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
23120 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
23130 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
23140 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
23150 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
23160 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
23170 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
23180 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
23190 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
231a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
231b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
231c0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
231d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
231e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
231f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
23200 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
23210 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
23220 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
23230 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
23240 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
23250 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
23260 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
23270 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
23280 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23290 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
232a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
232b0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
232c0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
232d0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
232e0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
232f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
23300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23310 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
23320 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
23330 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
23340 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
23350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
23360 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
23370 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
23380 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
23390 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
233a0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
233b0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
233c0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
233d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
233e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
233f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23400 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
23410 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
23420 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
23430 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
23440 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
23450 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
23460 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
23470 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
23480 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
23490 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
234a0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
234b0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
234c0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
234d0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
234e0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
234f0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
23500 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23510 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
23520 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
23530 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
23540 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
23550 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
23560 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
23570 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
23580 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
23590 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
235a0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
235b0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
235c0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
235d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
235e0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
235f0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
23600 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
23610 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
23620 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
23630 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
23640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
23650 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
23660 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
23670 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
23680 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
23690 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
236a0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
236b0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
236c0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
236d0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
236e0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
236f0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
23700 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
23710 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
23720 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
23730 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
23740 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
23750 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
23760 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
23770 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
23780 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
23790 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
237a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
237b0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
237c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
237d0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
237e0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
237f0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
23800 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
23810 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
23820 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23830 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
23840 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
23850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
23860 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
23870 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
23880 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23890 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
238a0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
238b0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
238c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
238d0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
238e0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
238f0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
23900 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
23910 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
23920 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
23930 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
23940 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
23950 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
23960 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
23970 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
23980 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
23990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
239a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
239b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
239c0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
239d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
239e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
239f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
23a00 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
23a10 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
23a20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
23a30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
23a40 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
23a50 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
23a60 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
23a70 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
23a80 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
23a90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
23aa0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
23ab0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
23ac0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
23ad0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
23ae0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
23af0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
23b00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
23b10 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
23b20 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
23b30 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
23b40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23b50 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
23b60 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
23b70 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
23b80 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
23b90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
23ba0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
23bb0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
23bc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23bd0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23be0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
23bf0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
23c00 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
23c10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
23c20 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
23c30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
23c40 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
23c50 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
23c60 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23c70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23c80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
23c90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
23ca0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
23cb0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
23cc0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
23cd0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
23ce0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
23cf0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
23d00 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
23d10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
23d20 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
23d30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
23d40 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
23d50 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
23d60 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
23d70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
23d80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
23d90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
23da0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
23db0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
23dc0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
23dd0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
23de0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
23df0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
23e00 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
23e10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
23e20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23e30 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
23e40 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
23e50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23e60 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
23e70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
23e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23e90 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
23ea0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
23eb0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
23ec0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
23ed0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
23ee0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
23ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23f00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
23f10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
23f20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
23f30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
23f40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
23f50 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
23f60 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
23f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23f80 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
23f90 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
23fa0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
23fb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
23fc0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
23fd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
23fe0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
23ff0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
24000 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
24010 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
24020 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
24030 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
24040 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
24050 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
24060 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
24070 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
24080 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
24090 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
240a0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
240b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
240c0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
240d0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
240e0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
240f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
24100 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
24110 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
24120 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
24130 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
24140 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
24150 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
24160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24170 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
24180 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24190 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
241a0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
241b0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
241c0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
241d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
241e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
241f0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
24200 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
24210 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
24220 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
24230 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
24240 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
24250 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
24260 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
24270 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
24280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24290 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
242a0 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
242b0 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   in UTF-16 in na
242c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
242d0 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
242e0 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74  ..** ^The zero t
242f0 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
24300 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
24310 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  s count..**.** ^
24320 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
24330 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
24340 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
24350 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
24360 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
24370 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
24380 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
24390 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
243a0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
243b0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
243c0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
243d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
243e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
243f0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
24400 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24410 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
24420 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
24430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
24440 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
24450 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
24460 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
24470 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
24480 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
24490 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
244a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
244b0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
244c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
244d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
244e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
244f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24500 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
24510 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
24520 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
24530 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
24540 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
24550 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
24560 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
24570 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
24580 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
24590 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
245a0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
245b0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
245c0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
245d0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
245e0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
245f0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
24600 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
24610 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
24620 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
24630 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
24640 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
24650 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
24660 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
24670 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
24680 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
24690 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
246a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
246b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
246c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
246d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
246e0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
246f0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
24700 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
24710 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
24720 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
24730 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
24740 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
24750 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
24760 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
24770 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
24780 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
24790 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
247a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
247b0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
247c0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
247d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
247e0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
247f0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
24800 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
24810 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
24820 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
24830 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
24840 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
24850 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
24860 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
24870 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
24880 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
24890 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
248a0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
248b0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
248c0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
248d0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
248e0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
248f0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
24900 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
24910 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
24920 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
24930 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
24940 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
24950 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
24960 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
24970 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
24980 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
24990 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
249a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
249b0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
249c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
249d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
249e0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
249f0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
24a00 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
24a10 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
24a20 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
24a30 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
24a40 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
24a50 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
24a60 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
24a70 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
24a80 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
24a90 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
24aa0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
24ab0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
24ac0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
24ad0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
24ae0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
24af0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
24b00 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
24b10 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
24b20 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
24b30 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
24b40 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
24b50 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
24b60 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
24b70 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
24b80 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
24b90 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
24ba0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
24bb0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
24bc0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
24bd0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
24be0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rammers..**.** ^
24bf0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
24c00 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
24c10 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
24c20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
24c30 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
24c40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
24c50 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
24c60 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
24c70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
24c80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
24c90 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
24ca0 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76  ..** ^(Type conv
24cb0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
24cc0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
24cd0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
24ce0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
24cf0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
24d00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
24d10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
24d20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
24d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24d40 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
24d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24d60 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
24d70 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
24d80 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
24d90 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
24da0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
24db0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
24dc0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
24dd0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
24de0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
24df0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
24e00 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
24e10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24e20 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
24e30 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
24e40 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
24e50 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
24e60 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
24e70 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
24e80 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
24e90 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
24ea0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
24eb0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
24ec0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
24ed0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
24ee0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
24ef0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
24f00 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
24f10 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f  /ul>)^.**.** ^Co
24f20 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
24f30 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
24f40 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
24f50 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
24f60 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
24f70 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
24f80 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
24f90 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
24fa0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
24fb0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
24fc0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
24fd0 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
24fe0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
24ff0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
25000 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
25010 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
25020 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
25030 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
25040 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
25050 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
25060 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
25070 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
25080 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
25090 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61  ..**.** ^(The sa
250a0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
250b0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
250c0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
250d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
250e0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
250f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
25100 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
25110 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
25120 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
25130 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
25140 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
25150 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
25160 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
25170 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
25180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25190 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
251a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
251b0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
251c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
251d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
251e0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  >.** </ul>)^.**.
251f0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
25200 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
25210 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
25220 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
25230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
25240 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
25250 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
25260 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
25270 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
25280 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
25290 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
252a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
252b0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
252c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
252d0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
252e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
252f0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
25300 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
25310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
25320 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
25330 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
25340 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
25350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25360 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
25370 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
25380 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25390 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
253a0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
253b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
253c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
253d0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
253e0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
253f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
25400 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
25410 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
25420 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
25430 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
25440 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
25450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
25460 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
25470 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
25480 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
25490 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
254a0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
254b0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
254c0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
254d0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
254e0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
254f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25500 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
25510 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
25520 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
25530 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
25540 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
25550 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
25560 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
25570 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
25580 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
25590 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
255a0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
255b0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
255c0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
255d0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
255e0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
255f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
25600 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
25610 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
25620 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
25630 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
25640 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
25650 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
25660 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
25670 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25680 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
25690 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
256a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
256b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
256c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
256d0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
256e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
256f0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
25700 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
25710 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
25720 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
25730 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25740 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
25750 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
25760 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
25770 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
25780 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
25790 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
257a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
257b0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
257c0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
257d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
257e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
257f0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
25800 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25810 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
25820 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25830 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
25840 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
25850 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25860 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
25870 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
25880 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
25890 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
258a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
258b0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
258c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
258d0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
258e0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
258f0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
25900 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
25910 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
25920 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
25930 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
25940 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
25950 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
25960 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
25970 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
25980 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
25990 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  ^If execution of
259a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
259b0 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
259c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
259d0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
259e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
259f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ed..**.** ^This 
25a00 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
25a10 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
25a20 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
25a30 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
25a40 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
25a50 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65  ement].  ^If the
25a60 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
25a70 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
25a80 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
25a90 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
25aa0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
25ab0 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
25ac0 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
25ad0 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
25ae0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
25af0 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e  terrupt]..** ^In
25b00 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
25b10 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
25b20 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
25b30 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
25b40 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
25b50 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
25b60 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
25b70 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
25b80 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
25b90 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e  TE_ABORT]..*/.in
25ba0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
25bb0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
25bc0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
25bd0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
25be0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
25bf0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
25c00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
25c10 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
25c20 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
25c30 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
25c40 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
25c50 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
25c60 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
25c70 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
25c80 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
25c90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
25ca0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
25cb0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
25cc0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
25cd0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25ce0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
25cf0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
25d00 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
25d10 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
25d20 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
25d30 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
25d40 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
25d50 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
25d60 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
25d70 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
25d80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25d90 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
25da0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
25db0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
25dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
25dd0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
25de0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25df0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
25e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25e10 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
25e20 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
25e30 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
25e40 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
25e50 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
25e60 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
25e70 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
25e80 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
25e90 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
25ea0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
25eb0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
25ec0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
25ed0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
25ee0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
25ef0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25f00 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
25f10 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
25f20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
25f30 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
25f40 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
25f50 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
25f60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25f70 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
25f80 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
25f90 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
25fa0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25fb0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
25fc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25fd0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
25fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
25ff0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
26000 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
26010 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
26020 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
26030 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
26040 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
26050 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
26060 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
26070 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
26080 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
26090 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
260a0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
260b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
260c0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
260d0 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
260e0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
260f0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
26100 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
26110 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
26120 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
26130 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
26140 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
26150 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
26160 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
26170 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
26180 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
26190 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
261a0 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
261b0 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
261c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
261d0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
261e0 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
261f0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
26200 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
26210 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
26220 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26230 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
26240 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
26250 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26260 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  16()..**.** ^The
26270 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26280 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
26290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
262a0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
262b0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
262c0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
262d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
262e0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
262f0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
26300 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
26310 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26320 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
26330 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
26340 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
26350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
26360 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  arately..**.** T
26370 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
26380 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
26390 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
263a0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
263b0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
263c0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
263d0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
263e0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
263f0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
26400 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65  f.** the zero-te
26410 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
26420 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
26430 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
26440 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
26450 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79  haracters.  ^Any
26460 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
26470 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
26480 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
26490 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
264a0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  in [SQLITE_ERROR
264b0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
264c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
264d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
264e0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
264f0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
26500 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
26510 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
26520 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
26530 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
26540 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
26550 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
26560 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
26570 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
26580 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
26590 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
265a0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
265b0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
265c0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
265d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
265e0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
265f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
26600 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
26610 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
26620 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26630 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
26640 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
26650 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
26660 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
26670 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
26680 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
26690 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
266a0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
266b0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
266c0 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
266d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
266e0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
266f0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
26700 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
26710 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
26720 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
26730 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
26740 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
26750 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
26760 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
26770 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
26780 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
26790 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
267a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
267b0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
267c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
267d0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
267e0 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
267f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
26800 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
26810 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
26820 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
26830 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
26840 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
26850 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
26860 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
26870 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
26880 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
26890 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
268a0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
268b0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
268c0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
268d0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
268e0 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
268f0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
26900 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
26910 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
26920 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
26930 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
26940 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
26950 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
26960 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
26970 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
26980 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
26990 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
269a0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
269b0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
269c0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
269d0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
269e0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].)^.**.** The
269f0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
26a00 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
26a10 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
26a20 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
26a30 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
26a40 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
26a50 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
26a60 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
26a70 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
26a80 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
26a90 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
26aa0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
26ab0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
26ac0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
26ad0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
26ae0 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
26af0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
26b00 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
26b10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
26b20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
26b30 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
26b40 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
26b50 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
26b60 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
26b70 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
26b80 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
26b90 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
26ba0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
26bb0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
26bc0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
26bd0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
26be0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
26bf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  s..**.** ^It is 
26c00 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
26c10 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
26c20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
26c30 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
26c40 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
26c50 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
26c60 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
26c70 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
26c80 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
26c90 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
26ca0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
26cb0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
26cc0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
26cd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
26ce0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
26cf0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
26d00 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
26d10 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
26d20 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
26d30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26d40 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
26d50 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
26d60 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
26d70 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
26d80 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
26d90 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
26da0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
26db0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
26dc0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
26dd0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
26de0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
26df0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
26e00 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
26e10 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26e20 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
26e30 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
26e40 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
26e50 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26e60 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
26e70 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
26e80 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
26e90 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
26ea0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
26eb0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
26ec0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
26ed0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
26ee0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
26ef0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
26f00 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
26f10 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
26f20 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
26f30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26f40 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66  tions..** ^The f
26f50 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  irst application
26f60 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26f70 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e  n with a given n
26f80 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c  ame overrides al
26f90 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75  l.** built-in fu
26fa0 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73  nctions in the s
26fb0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
26fc0 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74  nnection] with t
26fd0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
26fe0 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70   ^Subsequent app
26ff0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27000 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68   functions of th
27010 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79  e same name only
27020 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72   override .** pr
27030 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ior application-
27040 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27050 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78  s that are an ex
27060 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68  act match for th
27070 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70  e.** number of p
27080 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72  arameters and pr
27090 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67  eferred encoding
270a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
270b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
270c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
270d0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
270e0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
270f0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
27100 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
27110 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
27120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27130 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
27140 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
27150 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
27160 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
27170 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
27180 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
27190 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
271a0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
271b0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
271c0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
271d0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
271e0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
271f0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
27200 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
27210 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27220 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
27230 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
27240 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
27250 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
27260 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
27270 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
27280 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27290 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
272a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
272b0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
272c0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
272d0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
272e0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
272f0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
27300 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
27310 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
27320 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
27330 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
27340 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
27350 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27360 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
27370 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
27380 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
27390 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
273a0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
273b0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
273c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
273d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
273e0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
273f0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
27400 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
27410 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
27420 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
27430 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
27440 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
27450 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
27460 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
27470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
27480 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
27490 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
274a0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
274b0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
274c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
274d0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
274e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
274f0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
27500 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
27510 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
27520 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
27530 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
27540 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
27550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27560 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
27570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27580 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
27590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
275a0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
275b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
275c0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
275d0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
275e0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
275f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
27600 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
27610 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
27620 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
27630 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
27640 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
27650 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
27660 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
27670 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
27680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27690 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
276a0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
276b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
276c0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
276d0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
276e0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
276f0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
27700 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
27710 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
27720 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
27730 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
27740 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
27750 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
27760 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
27770 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
27780 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
27790 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
277a0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
277b0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
277c0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
277d0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
277e0 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
277f0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
27800 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
27810 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
27820 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
27830 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27840 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
27850 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
27860 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
27870 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
27880 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
27890 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
278a0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
278b0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
278c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
278d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
278e0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
278f0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
27900 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
27910 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
27920 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
27930 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
27940 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
27950 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
27960 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
27970 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
27980 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
27990 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
279a0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
279b0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
279c0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
279d0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
279e0 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
279f0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
27a00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
27a10 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
27a20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
27a30 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
27a40 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
27a50 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
27a60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
27a70 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
27a80 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
27a90 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
27aa0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
27ab0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
27ac0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
27ad0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
27ae0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
27af0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27b00 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
27b10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27b20 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
27b30 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
27b40 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
27b50 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
27b60 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
27b70 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
27b80 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
27b90 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
27ba0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
27bb0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
27bc0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27bd0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
27be0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27bf0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
27c00 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
27c10 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
27c20 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
27c30 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
27c40 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
27c50 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
27c60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27c70 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
27c80 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
27c90 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
27ca0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27cb0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
27cc0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
27cd0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
27ce0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
27cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27d00 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
27d10 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
27d20 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
27d30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
27d40 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
27d50 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
27d60 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
27d70 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
27d80 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
27d90 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
27da0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
27db0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27dc0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
27dd0 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
27de0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
27df0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
27e00 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
27e10 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
27e20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27e30 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
27e40 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
27e50 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
27e60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
27e70 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
27e80 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
27e90 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
27ea0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
27eb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
27ec0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
27ed0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
27ee0 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
27ef0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
27f00 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
27f10 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
27f20 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
27f30 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
27f40 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
27f50 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
27f60 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
27f70 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
27f80 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
27f90 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
27fa0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
27fb0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
27fc0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
27fd0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
27fe0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
27ff0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
28000 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
28010 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
28020 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
28030 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
28040 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
28050 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
28060 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
28070 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
28080 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
28090 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
280a0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
280b0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
280c0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
280d0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
280e0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
280f0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
28100 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
28110 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
28120 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
28130 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
28140 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
28150 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
28160 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28170 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
28180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28190 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
281a0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
281b0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
281c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
281d0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
281e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
281f0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
28200 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
28210 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
28220 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
28230 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
28240 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
28250 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
28260 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
28270 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
28280 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
28290 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
282a0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
282b0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
282c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
282d0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
282e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
282f0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
28300 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
28310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
28320 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
28330 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
28340 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
28350 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
28360 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
28370 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
28380 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
28390 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
283a0 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
283b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
283c0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
283d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
283e0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
283f0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
28400 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
28410 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
28420 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
28430 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
28440 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
28450 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28460 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28470 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
28480 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
28490 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
284a0 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
284b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
284c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
284d0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
284e0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
284f0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
28500 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
28510 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
28520 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
28530 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
28540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
28550 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
28560 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
28570 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
28580 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
28590 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
285a0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
285b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
285c0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
285d0 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
285e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
285f0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
28600 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
28610 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
28620 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
28630 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
28640 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28650 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
28660 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
28670 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
28680 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
28690 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
286a0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
286b0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
286c0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
286d0 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
286e0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
286f0 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
28700 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
28710 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
28720 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
28730 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
28740 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
28750 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
28760 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
28770 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
28780 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
28790 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
287a0 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
287b0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
287c0 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
287d0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
287e0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
287f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
28800 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
28810 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
28820 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
28830 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
28840 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
28850 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28860 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
28870 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
28880 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
28890 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
288a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
288b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
288c0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
288d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
288e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
288f0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
28900 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
28910 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
28920 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  y allocate error
28930 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
28940 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
28950 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
28960 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
28970 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
28980 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
28990 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
289a0 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
289b0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
289c0 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
289d0 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
289e0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
289f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
28a00 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
28a10 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
28a20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
28a30 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
28a40 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
28a50 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
28a60 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  tion.)^.**.** ^S
28a70 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
28a80 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
28a90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
28aa0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
28ab0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28ac0 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
28ad0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
28ae0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
28af0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28b00 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
28b10 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
28b20 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
28b30 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
28b40 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
28b50 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
28b60 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
28b70 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
28b80 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
28b90 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
28ba0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
28bb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
28bc0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
28bd0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
28be0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
28bf0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
28c00 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
28c10 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
28c20 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
28c30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28c40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28c50 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
28c60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28c70 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
28c80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
28c90 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
28ca0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
28cb0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
28cc0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
28cd0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
28ce0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
28cf0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
28d00 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
28d10 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
28d20 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
28d30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
28d40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
28d50 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
28d60 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
28d70 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
28d80 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
28d90 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
28da0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
28db0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
28dc0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
28dd0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
28de0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28df0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28e00 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
28e10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
28e20 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
28e30 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
28e40 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
28e50 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
28e60 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
28e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28e80 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
28e90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
28ea0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
28eb0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
28ec0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
28ed0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
28ee0 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
28ef0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
28f00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28f10 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
28f20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28f30 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
28f40 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
28f50 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
28f60 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
28f70 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
28f80 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
28f90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
28fa0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
28fb0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
28fc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
28fd0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
28fe0 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Data.**.** The 
28ff0 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
29000 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
29010 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
29020 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
29030 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
29040 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
29050 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
29060 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
29070 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
29080 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
29090 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
290a0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
290b0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
290c0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
290d0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
290e0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
290f0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
29100 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
29110 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
29120 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
29130 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
29140 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
29150 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
29160 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
29170 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
29180 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
29190 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
291a0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
291b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
291c0 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
291d0 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
291e0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
291f0 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
29200 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
29210 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
29220 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
29230 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
29240 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
29250 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
29260 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
29270 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
29280 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
29290 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
292a0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
292b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
292c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
292d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
292e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
292f0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
29300 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
29310 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
29320 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
29330 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
29340 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
29350 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
29360 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29370 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61  ion. ^If no meta
29380 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
29390 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
293a0 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
293b0 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
293c0 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
293d0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
293e0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
293f0 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
29400 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
29410 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
29420 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
29430 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
29440 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29450 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29460 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
29470 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
29480 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
29490 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
294a0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
294b0 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
294c0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
294d0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
294e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
294f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
29500 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
29510 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
29520 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
29530 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
29540 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
29550 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
29560 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69  troyed..** ^If i
29570 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
29580 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
29590 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
295a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
295b0 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
295c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
295d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
295e0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
295f0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
29600 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
29610 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
29620 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
29630 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
29640 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
29650 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
29660 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
29670 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
29680 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
29690 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
296a0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
296b0 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
296c0 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
296d0 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67  me.  ^The only g
296e0 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
296f0 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
29700 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
29710 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
29720 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
29730 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
29740 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
29750 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
29760 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
29770 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
29780 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
29790 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
297a0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
297b0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
297c0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
297d0 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a  arameters].)^.**
297e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
297f0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
29800 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
29810 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
29820 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
29830 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
29840 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
29850 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
29860 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
29870 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
29880 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
29890 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
298a0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
298b0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
298c0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
298d0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
298e0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
298f0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
29900 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
29910 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
29920 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
29930 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
29940 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
29950 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
29960 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
29970 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29980 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
29990 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
299a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
299b0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
299c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
299d0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
299e0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
299f0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
29a00 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
29a10 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
29a20 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
29a30 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
29a40 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
29a50 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
29a60 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
29a70 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
29a80 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
29a90 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
29aa0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
29ab0 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
29ac0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
29ad0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
29ae0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
29af0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
29b00 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
29b10 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
29b20 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
29b30 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
29b40 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
29b50 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
29b60 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
29b70 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
29b80 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
29b90 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
29ba0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
29bb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
29bc0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
29bd0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
29be0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
29bf0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
29c00 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
29c10 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
29c20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
29c30 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
29c40 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
29c50 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
29c60 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
29c70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
29c80 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
29c90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
29ca0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
29cb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
29cc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29cd0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
29ce0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
29cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
29d00 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
29d10 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
29d20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
29d30 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
29d40 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
29d50 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
29d60 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
29d70 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
29d80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
29d90 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
29da0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
29db0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
29dc0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
29dd0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
29de0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29df0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
29e00 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
29e10 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
29e20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29e30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
29e40 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
29e50 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
29e60 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
29e70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
29e80 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
29e90 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
29ea0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
29eb0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
29ec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29ed0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
29ee0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
29ef0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
29f00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29f10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29f20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
29f30 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
29f40 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
29f50 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
29f60 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
29f70 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
29f80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
29f90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29fa0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
29fb0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
29fc0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
29fd0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
29fe0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
29ff0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
2a000 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
2a010 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
2a020 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2a030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a040 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2a050 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2a060 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
2a070 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
2a080 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
2a090 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2a0a0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
2a0b0 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
2a0c0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
2a0d0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2a0e0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
2a0f0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
2a100 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
2a110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a120 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
2a130 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
2a140 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
2a150 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
2a160 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2a170 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
2a180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a190 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
2a1a0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
2a1b0 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
2a1c0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
2a1d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2a1e0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
2a1f0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
2a200 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
2a210 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2a220 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a230 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2a240 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a250 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2a260 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2a270 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2a280 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2a290 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2a2a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2a2b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
2a2c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2a2d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2a2e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2a2f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
2a300 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2a310 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
2a320 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2a330 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
2a340 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2a350 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
2a360 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2a370 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2a380 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a390 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2a3a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2a3b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2a3c0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
2a3d0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2a3e0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2a3f0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
2a400 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
2a410 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
2a420 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
2a430 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
2a440 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
2a450 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
2a460 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
2a470 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a480 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2a490 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
2a4a0 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
2a4b0 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
2a4c0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
2a4d0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
2a4e0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
2a4f0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
2a500 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
2a510 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
2a520 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
2a530 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2a540 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2a550 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2a560 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2a570 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2a580 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2a590 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
2a5a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a5b0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
2a5c0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2a5d0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2a5e0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
2a5f0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
2a600 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
2a610 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
2a620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a630 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
2a640 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2a650 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
2a660 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
2a670 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2a680 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2a690 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
2a6a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2a6b0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
2a6c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2a6d0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2a6e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2a6f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a700 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
2a710 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2a720 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2a730 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2a740 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
2a750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2a760 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
2a770 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2a780 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2a790 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a7a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2a7b0 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
2a7c0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2a7d0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2a7e0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2a7f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a800 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2a810 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2a820 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2a830 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2a840 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a850 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
2a860 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2a870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a880 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
2a890 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
2a8a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2a8b0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
2a8c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a8d0 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
2a8e0 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
2a8f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
2a900 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2a910 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a920 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
2a930 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
2a940 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
2a950 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
2a960 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2a970 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
2a980 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
2a990 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
2a9a0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
2a9b0 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
2a9c0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
2a9d0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
2a9e0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
2a9f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2aa00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
2aa10 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2aa20 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
2aa30 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2aa40 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2aa50 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2aa60 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
2aa70 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
2aa80 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
2aa90 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
2aaa0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
2aab0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2aac0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2aad0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2aae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2aaf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ab00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2ab10 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
2ab20 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
2ab30 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
2ab40 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
2ab50 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
2ab60 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
2ab70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
2ab80 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
2ab90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
2aba0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
2abb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2abc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2abd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2abe0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2abf0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2ac00 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2ac10 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2ac20 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2ac30 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2ac40 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2ac50 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2ac60 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2ac70 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2ac80 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2ac90 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2aca0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2acb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2acc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2acd0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
2ace0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
2acf0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2ad00 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2ad10 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
2ad20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
2ad30 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2ad40 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2ad50 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
2ad60 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
2ad70 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
2ad80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2ad90 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
2ada0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
2adb0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
2adc0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
2add0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
2ade0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
2adf0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2ae00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2ae10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ae20 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2ae30 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2ae40 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2ae50 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2ae60 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
2ae70 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
2ae80 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2ae90 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
2aea0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
2aeb0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
2aec0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
2aed0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
2aee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2aef0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2af00 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2af10 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
2af20 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2af30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2af40 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
2af50 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
2af60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2af70 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
2af80 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
2af90 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
2afa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2afb0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
2afc0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
2afd0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
2afe0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
2aff0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
2b000 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
2b010 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
2b020 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
2b030 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
2b040 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2b050 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2b060 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
2b070 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
2b080 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b090 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
2b0a0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
2b0b0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
2b0c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b0d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
2b0e0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
2b0f0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
2b100 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2b110 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
2b120 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
2b130 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
2b140 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2b150 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2b160 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
2b170 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
2b180 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
2b190 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
2b1a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b1b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
2b1c0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
2b1d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2b1e0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
2b1f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2b200 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
2b210 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2b220 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b230 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2b240 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2b250 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2b260 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2b270 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b280 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
2b290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b2a0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
2b2b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
2b2c0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
2b2d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b2e0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
2b2f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2b300 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
2b310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b320 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
2b330 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2b340 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b350 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
2b360 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2b370 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2b380 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2b390 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b3a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2b3b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2b3c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b3d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2b3e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2b3f0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
2b400 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
2b410 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
2b420 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
2b430 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2b440 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b450 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
2b460 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2b470 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
2b480 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2b490 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b4a0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
2b4b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2b4c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2b4d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2b4e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b4f0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
2b500 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2b510 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
2b520 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b530 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b540 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
2b550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2b560 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2b570 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b580 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b590 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
2b5a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
2b5b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
2b5c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b5d0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
2b5e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2b5f0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
2b600 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
2b610 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
2b620 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  nces.**.** These
2b630 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
2b640 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
2b650 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b660 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61  es to the.** [da
2b670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b680 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
2b690 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2b6a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
2b6b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63  ame of the new c
2b6c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b6d0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61  e is specified a
2b6e0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2b6f0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
2b700 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b710 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2b720 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2b730 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
2b740 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20  F-16 string for 
2b750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b760 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e 49  ollation16(). ^I
2b770 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
2b780 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
2b790 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
2b7a0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2b7b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  t..**.** ^The th
2b7c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  ird argument may
2b7d0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
2b7e0 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
2b7f0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
2b800 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20  TE_UTF16LE], or 
2b810 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2b820 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
2b830 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
2b840 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
2b850 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
2b860 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
2b870 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
2b880 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
2b890 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
2b8a0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
2b8b0 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70  big-endian, resp
2b8c0 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a 2a  ectively. ^The.*
2b8d0 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
2b8e0 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
2b8f0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f  SQLITE_UTF16] to
2b900 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74   indicate that t
2b910 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78  he routine.** ex
2b920 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
2b930 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69  o be UTF-16 stri
2b940 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ngs in the nativ
2b950 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72  e byte order, or
2b960 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
2b970 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f   can be [SQLITE_
2b980 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69  UTF16_ALIGNED] i
2b990 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75  f the.** the rou
2b9a0 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
2b9b0 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
2b9c0 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
2b9d0 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31  ings.** of UTF-1
2b9e0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
2b9f0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
2ba00 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
2ba10 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
2ba20 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2ba30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2ba40 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
2ba50 2e 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  .  ^If it is NUL
2ba60 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73  L, this is the s
2ba70 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20  ame as deleting 
2ba80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2ba90 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68   sequence (so th
2baa0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74  at SQLite cannot
2bab0 20 63 61 6c 6c 20 69 74 20 61 6e 79 20 6d 6f 72   call it any mor
2bac0 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d  e)..** ^Each tim
2bad0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
2bae0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
2baf0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
2bb00 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
2bb10 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
2bb20 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
2bb30 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
2bb40 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
2bb50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
2bb60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2bb70 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
2bb80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bb90 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
2bba0 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20   ^The remaining 
2bbb0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2bbc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
2bbd0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
2bbe0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
2bbf0 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
2bc00 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
2bc10 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
2bc20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
2bc30 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
2bc40 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
2bc50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2bc60 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
2bc70 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
2bc80 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
2bc90 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2bca0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
2bcb0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
2bcc0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
2bcd0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
2bce0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
2bcf0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
2bd00 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
2bd10 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
2bd20 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
2bd30 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
2bd40 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
2bd50 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
2bd60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bd70 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
2bd80 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
2bd90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2bda0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
2bdb0 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
2bdc0 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
2bdd0 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
2bde0 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
2bdf0 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65  lation.  ^The de
2be00 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2be10 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
2be20 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
2be30 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
2be40 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
2be50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2be60 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
2be70 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
2be80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2be90 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f  ion_v2()..** ^Co
2bea0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
2beb0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
2bec0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
2bed0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
2bee0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
2bef0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
2bf00 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
2bf10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2bf20 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
2bf30 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2bf40 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
2bf50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2bf60 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2bf70 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2bf80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2bf90 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2bfa0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2bfb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2bfc0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2bfd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2bfe0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2bff0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2c000 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2c010 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2c020 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2c030 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2c040 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2c050 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2c060 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2c070 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2c080 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2c090 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2c0a0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2c0b0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2c0c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
2c0d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2c0e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
2c0f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2c100 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2c110 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2c120 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2c130 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2c140 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2c150 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2c160 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2c170 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2c180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c190 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
2c1a0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
2c1b0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
2c1c0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
2c1d0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
2c1e0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
2c1f0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2c200 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
2c210 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
2c220 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
2c230 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
2c240 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2c250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
2c260 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2c270 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
2c280 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2c290 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
2c2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c2b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
2c2c0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
2c2d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c2e0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
2c2f0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
2c300 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
2c310 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
2c320 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2c330 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
2c340 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
2c350 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
2c360 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2c370 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
2c380 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
2c390 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2c3a0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
2c3b0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
2c3c0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
2c3d0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
2c3e0 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
2c3f0 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
2c400 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2c410 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
2c420 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2c430 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2c440 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2c450 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2c460 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2c470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c480 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2c490 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2c4a0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2c4b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2c4c0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2c4d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2c4e0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
2c4f0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2c500 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
2c510 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2c520 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2c530 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
2c540 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
2c550 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
2c560 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2c570 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
2c580 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
2c590 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2c5a0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2c5b0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2c5c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2c5d0 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
2c5e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2c5f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
2c600 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
2c610 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
2c620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2c630 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
2c640 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2c650 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
2c660 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2c670 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c680 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
2c690 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2c6a0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2c6b0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2c6c0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2c6d0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2c6e0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2c6f0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2c700 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2c710 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2c720 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2c730 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2c740 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2c750 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2c760 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
2c770 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
2c780 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
2c790 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
2c7a0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
2c7b0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
2c7c0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
2c7d0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
2c7e0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
2c7f0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
2c800 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
2c810 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
2c820 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
2c830 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
2c840 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
2c850 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
2c860 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c870 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c880 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2c890 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2c8a0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2c8b0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
2c8c0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2c8d0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
2c8e0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
2c8f0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
2c900 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
2c910 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
2c920 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
2c930 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
2c940 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
2c950 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
2c960 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
2c970 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
2c980 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2c990 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2c9a0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2c9b0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2c9c0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2c9d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2c9e0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
2c9f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ca00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ca10 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2ca20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2ca30 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2ca40 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
2ca50 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2ca60 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2ca70 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2ca80 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
2ca90 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
2caa0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
2cab0 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
2cac0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2cad0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2cae0 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
2caf0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
2cb00 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
2cb10 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
2cb20 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
2cb30 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
2cb40 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
2cb50 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
2cb60 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
2cb70 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
2cb80 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2cb90 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2cba0 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
2cbb0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
2cbc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
2cbd0 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
2cbe0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2cbf0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2cc00 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2cc10 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2cc20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cc30 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
2cc40 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
2cc50 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  me.**.** ^The sq
2cc60 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
2cc70 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
2cc80 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
2cc90 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
2cca0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
2ccb0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
2ccc0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
2ccd0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
2cce0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2ccf0 20 5e 49 66 20 74 68 65 20 6f 70 65 72 61 74 69   ^If the operati
2cd00 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
2cd10 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
2cd20 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
2cd30 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
2cd40 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
2cd50 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
2cd60 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
2cd70 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
2cd80 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e  t second. ^The n
2cd90 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2cda0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
2cdb0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
2cdc0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
2cdd0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
2cde0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2cdf0 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
2ce00 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2ce10 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2ce20 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2ce30 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2ce40 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2ce50 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  s] object..*/.in
2ce60 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
2ce70 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ce80 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
2ce90 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
2cea0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
2ceb0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
2cec0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
2ced0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
2cee0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
2cef0 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
2cf00 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
2cf10 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
2cf20 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
2cf30 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
2cf40 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
2cf50 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
2cf60 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
2cf70 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
2cf80 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
2cf90 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
2cfa0 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
2cfb0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
2cfc0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2cfd0 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
2cfe0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
2cff0 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
2d000 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
2d010 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
2d020 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
2d030 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
2d040 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
2d050 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
2d060 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
2d070 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
2d080 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2d090 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2d0a0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
2d0b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d0c0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
2d0d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2d0e0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
2d0f0 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
2d100 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
2d110 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2d120 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
2d130 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
2d140 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
2d150 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
2d160 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2d170 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
2d180 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
2d190 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2d1a0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
2d1b0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
2d1c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2d1d0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2d1e0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
2d1f0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
2d200 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
2d210 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
2d220 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2d230 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2d240 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
2d250 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
2d260 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2d270 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
2d280 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
2d290 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
2d2a0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2d2b0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
2d2c0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
2d2d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
2d2e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2d2f0 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
2d300 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
2d310 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
2d320 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2d330 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
2d340 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
2d350 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
2d360 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
2d370 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
2d380 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
2d390 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2d3a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2d3b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d3c0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
2d3d0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
2d3e0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2d3f0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
2d400 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
2d410 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
2d420 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
2d430 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
2d440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d450 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
2d460 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
2d470 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
2d480 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
2d490 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2d4a0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
2d4b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d4c0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
2d4d0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
2d4e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d4f0 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
2d500 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
2d510 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
2d520 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
2d530 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
2d540 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
2d550 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2d560 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
2d570 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
2d580 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2d590 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
2d5a0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
2d5b0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
2d5c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
2d5d0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
2d5e0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
2d5f0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
2d600 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
2d610 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
2d620 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
2d630 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
2d640 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
2d650 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2d660 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
2d670 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
2d680 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
2d690 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
2d6a0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
2d6b0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
2d6c0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
2d6d0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
2d6e0 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
2d6f0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2d700 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
2d710 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
2d720 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
2d730 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
2d740 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
2d750 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
2d760 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
2d770 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
2d780 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2d790 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
2d7a0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
2d7b0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
2d7c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2d7d0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2d7e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d7f0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2d800 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
2d810 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
2d820 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
2d830 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
2d840 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2d850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d860 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
2d870 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2d880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d890 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2d8a0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
2d8b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d8c0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
2d8d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d8e0 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
2d8f0 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
2d900 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
2d910 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d920 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
2d930 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
2d940 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
2d950 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d960 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
2d970 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
2d980 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
2d990 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
2d9a0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
2d9b0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
2d9c0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2d9d0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2d9e0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2d9f0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2da00 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
2da10 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
2da20 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2da30 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2da40 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
2da50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2da60 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
2da70 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
2da80 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2da90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
2daa0 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73  b.  ^If pStmt is
2dab0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
2dac0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2dad0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2dae0 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
2daf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2db00 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2db10 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
2db20 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
2db30 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20  ^If no prepared 
2db40 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
2db50 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
2db60 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
2db70 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
2db80 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
2db90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2dba0 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
2dbb0 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
2dbc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
2dbd0 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
2dbe0 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
2dbf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2dc00 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
2dc10 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
2dc20 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
2dc30 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
2dc40 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
2dc50 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
2dc60 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
2dc70 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2dc80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2dc90 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
2dca0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
2dcb0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2dcc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
2dcd0 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
2dce0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2dcf0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2dd00 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2dd10 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2dd20 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f  ansaction is [CO
2dd30 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64  MMIT | committed
2dd40 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2dd50 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2dd60 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2dd70 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2dd80 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2dd90 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2dda0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2ddb0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73  idden..** ^The s
2ddc0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2ddd0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2dde0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2ddf0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2de00 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2de10 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2de20 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
2de30 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
2de40 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  k]..** ^Any call
2de50 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2de60 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
2de70 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2de80 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2de90 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2dea0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2deb0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2dec0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
2ded0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
2dee0 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
2def0 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  k..** ^If the ca
2df00 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
2df10 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
2df20 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2df30 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
2df40 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
2df50 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
2df60 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ck..**.** ^The s
2df70 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2df80 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71  ok(D,C,P) and sq
2df90 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2dfa0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
2dfb0 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ions.** return t
2dfc0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
2dfd0 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2dfe0 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65  call of the same
2dff0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20   function.** on 
2e000 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2e010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2e020 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
2e030 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2e040 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f  for each functio
2e050 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68  n on D..**.** Th
2e060 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65  e callback imple
2e070 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
2e080 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
2e090 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
2e0a0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2e0b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2e0c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  invoked the call
2e0d0 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  back.  Any actio
2e0e0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
2e0f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e100 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
2e110 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
2e120 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
2e130 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
2e140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2e150 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
2e160 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a  ed the commit.**
2e170 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f   or rollback hoo
2e180 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  k in the first p
2e190 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  lace..** Note th
2e1a0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
2e1b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2e1c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
2e1d0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
2e1e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
2e1f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
2e200 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
2e210 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
2e220 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
2e230 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
2e240 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
2e250 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
2e260 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
2e270 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
2e280 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
2e290 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
2e2a0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
2e2b0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
2e2c0 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
2e2d0 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
2e2e0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
2e2f0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2e300 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
2e310 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
2e320 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
2e330 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
2e340 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
2e350 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
2e360 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
2e370 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
2e380 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
2e390 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
2e3a0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
2e3b0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
2e3c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
2e3d0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
2e3e0 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
2e3f0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
2e400 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
2e410 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
2e420 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
2e430 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
2e440 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
2e450 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
2e460 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
2e470 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
2e480 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
2e490 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
2e4a0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
2e4b0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
2e4c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
2e4d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2e4e0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
2e4f0 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
2e500 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
2e510 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  losed..**.** See
2e520 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2e530 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2e540 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
2e550 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2e560 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
2e570 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
2e580 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
2e590 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
2e5a0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
2e5b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
2e5c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2e5d0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
2e5e0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
2e5f0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
2e600 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e610 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
2e620 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2e630 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
2e640 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
2e650 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2e660 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
2e670 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
2e680 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2e690 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2e6a0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
2e6b0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2e6c0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
2e6d0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2e6e0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2e6f0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
2e700 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
2e710 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2e720 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2e730 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
2e740 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2e750 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
2e760 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
2e770 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
2e780 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
2e790 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
2e7a0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
2e7b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2e7c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2e7d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2e7e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
2e7f0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
2e800 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
2e810 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
2e820 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
2e830 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2e840 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
2e850 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
2e860 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
2e870 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2e880 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
2e890 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
2e8a0 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
2e8b0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
2e8c0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2e8d0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2e8e0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2e8f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2e900 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
2e910 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
2e920 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
2e930 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
2e940 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
2e950 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2e960 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
2e970 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
2e980 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
2e990 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
2e9a0 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
2e9b0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
2e9c0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
2e9d0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
2e9e0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2e9f0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
2ea00 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
2ea10 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
2ea20 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
2ea30 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
2ea40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
2ea50 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2ea60 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
2ea70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
2ea80 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2ea90 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
2eaa0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
2eab0 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
2eac0 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
2ead0 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
2eae0 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
2eaf0 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
2eb00 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
2eb10 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
2eb20 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
2eb30 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
2eb40 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
2eb50 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
2eb60 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
2eb70 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
2eb80 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
2eb90 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2eba0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
2ebb0 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
2ebc0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
2ebd0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
2ebe0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
2ebf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2ec00 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
2ec10 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
2ec20 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
2ec30 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
2ec40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2ec50 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
2ec60 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
2ec70 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
2ec80 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
2ec90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2eca0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
2ecb0 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
2ecc0 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
2ecd0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
2ece0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2ecf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
2ed00 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
2ed10 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
2ed20 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
2ed30 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
2ed40 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
2ed50 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
2ed60 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2ed70 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
2ed80 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
2ed90 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
2eda0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
2edb0 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
2edc0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2edd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
2ede0 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
2edf0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
2ee00 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
2ee10 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2ee20 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
2ee30 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
2ee40 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
2ee50 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f  nterfaces..*/.vo
2ee60 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
2ee70 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
2ee80 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
2ee90 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
2eea0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
2eeb0 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
2eec0 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
2eed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2eee0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
2eef0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
2ef00 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52   Cache.** KEYWOR
2ef10 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
2ef20 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e}.**.** ^(This 
2ef30 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
2ef40 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
2ef50 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
2ef60 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
2ef70 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
2ef80 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
2ef90 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  een [database co
2efa0 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65  nnection | conne
2efb0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68  ctions].** to th
2efc0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
2efd0 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
2efe0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2eff0 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61  ent is true.** a
2f000 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
2f010 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66  he argument is f
2f020 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  alse.)^.**.** ^C
2f030 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
2f040 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
2f050 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69  bled for an enti
2f060 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54  re process..** T
2f070 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
2f080 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
2f090 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70  sion 3.5.0. In p
2f0a0 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
2f0b0 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72   SQLite,.** shar
2f0c0 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20  ing was enabled 
2f0d0 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
2f0e0 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
2f0f0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  rately..**.** ^(
2f100 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
2f110 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
2f120 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
2f130 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
2f140 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2f150 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2f160 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2f170 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
2f180 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
2f190 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62  * Existing datab
2f1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2f1b0 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65  continue use the
2f1c0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a   sharing mode.**
2f1d0 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66   that was in eff
2f1e0 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20  ect at the time 
2f1f0 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64  they were opened
2f200 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
2f210 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f220 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
2f230 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
2f240 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2f250 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
2f260 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
2f270 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2f280 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a  ed otherwise.)^.
2f290 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61  **.** ^Shared ca
2f2a0 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
2f2b0 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20  by default. But 
2f2c0 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
2f2d0 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72  e in.** future r
2f2e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2f2f0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
2f300 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74   that care about
2f310 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
2f320 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20   setting should 
2f330 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c  set it explicitl
2f340 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73  y..**.** See Als
2f350 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72  o:  [SQLite Shar
2f360 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a  ed-Cache Mode].*
2f370 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2f380 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2f390 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2f3a0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2f3b0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2f3c0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  mory.**.** ^The 
2f3d0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2f3e0 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
2f3f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
2f400 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
2f410 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
2f420 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
2f430 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
2f440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
2f450 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
2f460 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
2f470 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f    Memory used to
2f480 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a   cache database.
2f490 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  ** pages to impr
2f4a0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
2f4b0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
2f4c0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2f4d0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74  emory..** ^sqlit
2f4e0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2f4f0 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
2f500 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f510 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
2f520 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
2f530 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
2f540 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
2f550 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  equested..** ^Th
2f560 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
2f570 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69  e_memory() routi
2f580 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65  ne is a no-op re
2f590 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20  turning zero.** 
2f5a0 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74  if SQLite is not
2f5b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
2f5c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
2f5d0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
2f5e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f5f0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2f600 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2f610 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
2f620 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
2f630 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ze.**.** ^The sq
2f640 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2f650 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2f660 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2f670 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2f680 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2f690 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2f6a0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2f6b0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20   SQLite..** ^If 
2f6c0 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
2f6d0 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
2f6e0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
2f6f0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
2f700 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
2f710 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2f720 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
2f730 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
2f740 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
2f750 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
2f760 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
2f770 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
2f780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69  d..**.** ^The li
2f790 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
2f7a0 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20  oft" because if 
2f7b0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2f7c0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
2f7d0 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
2f7e0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
2f7f0 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
2f800 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
2f810 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
2f820 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
2f830 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
2f840 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
2f850 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
2f860 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72  * ^A negative or
2f870 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2f880 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2f890 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2f8a0 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2f8b0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2f8c0 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2f8d0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2f8e0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2f8f0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  hausted..** ^The
2f900 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2f910 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2f920 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2f930 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d  **.** ^(SQLite m
2f940 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2f950 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2f960 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2f970 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2f980 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2f990 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2f9a0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2f9b0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2f9c0 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2f9d0 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54  tification.)^  T
2f9e0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
2f9f0 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  imit is.** calle
2fa00 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
2fa10 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
2fa20 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
2fa30 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
2fa40 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
2fa50 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
2fa60 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
2fa70 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2fa80 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
2fa90 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
2faa0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2fab0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2fac0 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
2fad0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
2fae0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
2faf0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2fb00 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
2fb10 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
2fb20 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
2fb30 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
2fb40 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
2fb50 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2fb60 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
2fb70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2fb80 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
2fb90 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
2fba0 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
2fbb0 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
2fbc0 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
2fbd0 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
2fbe0 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
2fbf0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2fc00 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2fc10 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2fc20 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2fc30 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2fc40 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2fc50 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
2fc60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2fc70 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2fc80 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2fc90 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2fca0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2fcb0 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2fcc0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2fcd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2fce0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2fcf0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2fd00 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2fd10 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2fd20 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2fd30 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2fd40 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2fd50 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2fd60 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
2fd70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2fd80 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
2fd90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2fda0 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
2fdb0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
2fdc0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2fdd0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2fde0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2fdf0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2fe00 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
2fe10 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2fe20 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2fe30 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2fe40 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2fe50 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2fe60 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2fe70 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2fe80 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2fe90 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2fea0 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2feb0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
2fec0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2fed0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2fee0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2fef0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2ff00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2ff10 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2ff20 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2ff30 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2ff40 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2ff50 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
2ff60 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
2ff70 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
2ff80 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
2ff90 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
2ffa0 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
2ffb0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
2ffc0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2ffd0 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
2ffe0 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2fff0 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
30000 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
30010 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
30020 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
30030 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
30040 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
30050 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
30060 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
30070 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
30080 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
30090 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
300a0 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
300b0 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
300c0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
300d0 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
300e0 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
300f0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
30100 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
30110 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
30120 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
30130 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
30140 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
30150 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
30160 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
30170 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
30180 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
30190 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
301a0 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
301b0 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
301c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
301d0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
301e0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
301f0 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
30200 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
30210 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
30220 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
30230 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
30240 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
30250 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
30260 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
30270 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
30280 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
30290 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
302a0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
302b0 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
302c0 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
302d0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
302e0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
302f0 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
30300 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
30310 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
30320 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30330 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
30340 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
30350 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
30360 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
30370 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
30380 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
30390 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
303a0 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
303b0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
303c0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
303d0 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
303e0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
303f0 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
30400 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
30410 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
30420 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
30430 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
30440 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
30450 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
30460 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
30470 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
30480 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
30490 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
304a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
304b0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
304c0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
304d0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
304e0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
304f0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
30500 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
30510 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
30520 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
30530 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
30540 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
30550 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
30560 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
30570 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
30580 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
30590 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
305a0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
305b0 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
305c0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
305d0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
305e0 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
305f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30600 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
30610 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
30620 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
30630 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
30640 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
30650 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
30660 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
30670 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
30680 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
30690 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
306a0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
306b0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
306c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
306d0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
306e0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
306f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
30700 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
30710 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
30720 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
30730 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
30740 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
30750 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
30760 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
30770 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
30780 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
30790 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
307a0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
307b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
307c0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
307d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
307e0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
307f0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
30800 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
30810 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
30820 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
30830 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
30840 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
30850 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
30860 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
30870 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
30880 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
30890 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
308a0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
308b0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
308c0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
308d0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
308e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
308f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
30900 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
30910 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
30920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
30930 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
30940 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
30950 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
30960 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
30970 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
30980 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
30990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
309a0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
309b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
309c0 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
309d0 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
309e0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
309f0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
30a00 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
30a10 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
30a20 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
30a30 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
30a40 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
30a50 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
30a60 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
30a70 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
30a80 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
30a90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30aa0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
30ab0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30ac0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
30ad0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
30ae0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
30af0 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
30b00 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
30b10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
30b20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
30b30 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
30b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
30b50 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
30b60 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
30b70 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
30b80 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
30b90 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
30ba0 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
30bb0 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
30bc0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
30bd0 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
30be0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
30bf0 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
30c00 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
30c10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
30c20 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
30c30 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
30c40 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
30c50 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
30c60 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30c70 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
30c80 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
30c90 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
30ca0 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
30cb0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
30cc0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
30cd0 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
30ce0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
30cf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30d00 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
30d10 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
30d20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
30d30 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
30d40 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
30d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
30d60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
30d70 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
30d80 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
30d90 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
30da0 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
30db0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
30dc0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
30dd0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
30de0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
30df0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
30e00 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
30e10 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
30e20 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
30e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30e40 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
30e50 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
30e60 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
30e70 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
30e80 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
30e90 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
30ea0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
30eb0 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
30ec0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
30ed0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
30ee0 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
30ef0 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
30f00 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
30f10 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
30f20 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
30f30 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
30f40 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
30f50 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
30f60 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
30f70 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
30f80 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
30f90 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
30fa0 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
30fb0 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
30fc0 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
30fd0 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
30fe0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30ff0 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
31000 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
31010 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
31020 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
31030 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
31040 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
31050 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
31060 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
31070 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
31080 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
31090 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
310a0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
310b0 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
310c0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
310d0 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
310e0 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
310f0 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
31100 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
31110 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
31120 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
31130 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
31140 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
31150 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
31160 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b  .** to all new [
31170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31180 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ions]..**.** ^(T
31190 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
311a0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
311b0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e  the extension en
311c0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20  try point.** in 
311d0 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
311e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
311f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
31200 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a  ].  That memory.
31210 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65  ** is deallocate
31220 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65  d by [sqlite3_re
31230 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
31240 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  on()].)^.**.** ^
31250 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
31260 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
31270 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
31280 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f   that is.** auto
31290 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
312a0 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
312b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
312c0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65  ction].** is ope
312d0 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
312e0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
312f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
31300 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
31310 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44  pen_v2()]..** ^D
31320 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
31330 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
31340 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
31350 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74   routine.** mult
31360 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20  iple times with 
31370 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
31380 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
31390 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78  ** ^Automatic ex
313a0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
313b0 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
313c0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
313d0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
313e0 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
313f0 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
31400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
31410 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
31420 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
31430 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
31440 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
31450 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
31460 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
31470 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
31480 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20  . It undoes the 
31490 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
314a0 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
314b0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
314c0 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a  ] calls.)^.**.**
314d0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
314e0 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
314f0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
31500 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
31510 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31520 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
31530 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
31540 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
31550 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
31560 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
31570 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
31580 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
31590 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
315a0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
315b0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
315c0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
315d0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
315e0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
315f0 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
31600 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
31610 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
31620 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
31630 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
31640 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
31650 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
31660 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
31670 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
31680 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
31690 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
316a0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
316b0 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
316c0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
316d0 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
316e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
316f0 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
31700 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
31710 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
31720 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
31730 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
31740 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
31750 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31760 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
31770 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
31780 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
31790 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
317a0 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
317b0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
317c0 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  able Object.** K
317d0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
317e0 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
317f0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
31800 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
31810 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
31820 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
31830 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
31840 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
31850 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31860 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
31870 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
31880 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
31890 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
318a0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
318b0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
318c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
318d0 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
318e0 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
318f0 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
31900 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
31910 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
31920 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
31930 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
31940 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
31950 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
31960 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
31970 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
31980 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
31990 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
319a0 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
319b0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
319c0 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
319d0 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
319e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
319f0 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
31a00 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
31a10 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
31a20 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
31a30 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
31a40 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
31a50 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
31a60 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
31a70 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
31a80 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
31a90 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
31aa0 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
31ab0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
31ac0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
31ad0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
31ae0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
31af0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
31b00 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
31b10 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
31b20 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
31b30 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
31b40 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31b50 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
31b60 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
31b70 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
31b80 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
31b90 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
31ba0 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
31bb0 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
31bc0 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
31bd0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
31be0 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
31bf0 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
31c00 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31c10 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
31c20 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
31c30 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
31c40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31c50 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
31c60 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
31c70 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
31c80 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
31c90 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
31ca0 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
31cb0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
31cc0 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
31cd0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
31ce0 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
31cf0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
31d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
31d10 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
31d20 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
31d30 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
31d40 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
31d50 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
31d60 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
31d70 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
31d80 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
31d90 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
31da0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
31db0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
31dc0 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
31dd0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
31de0 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
31df0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
31e00 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
31e10 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
31e20 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
31e30 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
31e40 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
31e50 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
31e60 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31e70 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
31e80 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
31e90 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31ea0 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
31eb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31ec0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
31ed0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
31ee0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
31ef0 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
31f00 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
31f10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31f20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
31f30 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31f40 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31f50 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
31f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31f70 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
31f80 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
31f90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31fa0 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
31fb0 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
31fc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
31fd0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
31fe0 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
31ff0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
32000 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
32010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
32020 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
32030 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
32040 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
32050 20 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a   used as part.**
32060 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
32070 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63   table] interfac
32080 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  e to.** pass inf
32090 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
320a0 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
320b0 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
320c0 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
320d0 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
320e0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
320f0 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
32100 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
32110 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
32120 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
32130 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
32140 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
32150 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
32160 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
32170 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
32180 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
32190 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
321a0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
321b0 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
321c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
321d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
321e0 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c  >column OP expr<
321f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
32200 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d  ** where OP is =
32210 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
32220 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e  gt;, or &gt;=.)^
32230 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c    ^(The particul
32240 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a  ar operator is.*
32250 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e  * stored in aCon
32260 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69  straint[].op usi
32270 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ng one of the.**
32280 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43   [SQLITE_INDEX_C
32290 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53  ONSTRAINT_EQ | S
322a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
322b0 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e  TRAINT_ values].
322c0 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65  )^.** ^(The inde
322d0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
322e0 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
322f0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
32300 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e  olumn.)^  ^(aCon
32310 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65  straint[].usable
32320 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a   is TRUE if the.
32330 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72  ** expr on the r
32340 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63  ight-hand side c
32350 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  an be evaluated 
32360 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f  (and thus the co
32370 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75  nstraint.** is u
32380 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65  sable) and false
32390 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e   if it cannot.)^
323a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69  .**.** ^The opti
323b0 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
323c0 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
323d0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
323e0 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
323f0 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
32400 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
32410 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
32420 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
32430 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
32440 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
32450 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
32460 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
32470 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
32480 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61  ** ^The aConstra
32490 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
324a0 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
324b0 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74  lause terms that
324c0 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74   are.** relevant
324d0 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
324e0 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
324f0 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
32500 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69  **.** ^Informati
32510 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44  on about the ORD
32520 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
32530 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72  stored in aOrder
32540 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74  By[]..** ^Each t
32550 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20  erm of aOrderBy 
32560 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e  records a column
32570 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
32580 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54   clause..**.** T
32590 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20  he [xBestIndex] 
325a0 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c  method must fill
325b0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
325c0 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  e[] with informa
325d0 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68  tion.** about wh
325e0 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  at parameters to
325f0 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72   pass to xFilter
32600 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78  .  ^If argvIndex
32610 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
32620 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
32630 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
32640 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
32650 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
32660 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
32670 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
32680 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e  ntry in argv.  ^
32690 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  (If aConstraintU
326a0 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
326b0 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
326c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
326d0 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
326e0 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
326f0 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
32700 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
32710 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
32720 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  QLite.)^.**.** ^
32730 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69  The idxNum and i
32740 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65  dxPtr values are
32750 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61   recorded and pa
32760 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ssed into the.**
32770 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f   [xFilter] metho
32780 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f  d..** ^[sqlite3_
32790 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20  free()] is used 
327a0 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
327b0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
327c0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
327d0 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
327e0 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e   ^The orderByCon
327f0 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
32800 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46   output from [xF
32810 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77  ilter]/[xNext] w
32820 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
32830 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
32840 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
32850 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
32860 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
32870 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
32880 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
32890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74  ..**.** ^The est
328a0 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
328b0 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
328c0 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
328d0 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
328e0 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
328f0 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
32900 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
32910 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
32920 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
32930 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
32940 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
32950 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
32960 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
32970 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
32980 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
32990 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
329a0 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
329b0 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
329c0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
329d0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
329e0 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
329f0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
32a00 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
32a10 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
32a20 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
32a30 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
32a40 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
32a50 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
32a60 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
32a70 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
32a80 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
32a90 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
32aa0 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
32ab0 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
32ac0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
32ad0 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
32ae0 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
32af0 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
32b00 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
32b10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
32b20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
32b30 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
32b40 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
32b50 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
32b60 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
32b70 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
32b80 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
32b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32ba0 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
32bb0 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
32bc0 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
32bd0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
32be0 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
32bf0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
32c00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
32c10 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
32c20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
32c30 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
32c40 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
32c50 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
32c60 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
32c70 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
32c80 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
32c90 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f  clause */.  /* O
32ca0 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
32cb0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
32cc0 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
32cd0 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
32ce0 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
32cf0 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
32d00 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
32d10 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
32d20 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
32d30 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
32d40 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
32d50 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
32d60 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
32d70 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
32d80 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
32d90 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
32da0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
32db0 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
32dc0 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
32dd0 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
32de0 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
32df0 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
32e00 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
32e10 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
32e20 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
32e30 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
32e40 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
32e50 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
32e60 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
32e70 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
32e80 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
32e90 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
32ea0 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
32eb0 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
32ec0 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
32ed0 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
32ee0 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
32ef0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
32f00 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
32f10 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f  ble Constraint O
32f20 70 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a  perator Codes.**
32f30 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
32f40 20 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c   defined the all
32f50 6f 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20  owed values for 
32f60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
32f70 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e  index_info].aCon
32f80 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65  straint[].op fie
32f90 6c 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20  ld.  Each value 
32fa0 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e  represents.** an
32fb0 20 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69   operator that i
32fc0 73 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73  s part of a cons
32fd0 74 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74  traint term in t
32fe0 68 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20  he wHERE clause 
32ff0 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68  of.** a query th
33000 61 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75  at uses a [virtu
33010 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64  al table]..*/.#d
33020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
33030 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
33040 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
33050 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
33060 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64  RAINT_GT    4.#d
33070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
33080 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45  EX_CONSTRAINT_LE
33090 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
330a0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
330b0 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23  RAINT_LT    16.#
330c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
330d0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
330e0 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
330f0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
33100 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34  STRAINT_MATCH 64
33110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33120 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72  : Register A Vir
33130 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65  tual Table Imple
33140 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  mentation.**.** 
33150 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
33160 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69  are used to regi
33170 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74  ster a new [virt
33180 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
33190 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75  ] name..** ^Modu
331a0 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
331b0 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
331c0 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61  re.** creating a
331d0 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
331e0 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d  ble] using the m
331f0 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65  odule and before
33200 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65   using a.** pree
33210 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c  xisting [virtual
33220 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20   table] for the 
33230 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  module..**.** ^T
33240 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69  he module name i
33250 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20  s registered on 
33260 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33270 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
33280 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  ied.** by the fi
33290 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
332a0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
332b0 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e   module is given
332c0 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f   by the .** seco
332d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
332e0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
332f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
33300 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65   to.** the imple
33310 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
33320 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
33330 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20  module].   ^The 
33340 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
33350 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
33360 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ary client data 
33370 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
33380 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
33390 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65  * into the [xCre
333a0 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
333b0 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ct] methods of t
333c0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
333d0 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20   module.** when 
333e0 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61  a new virtual ta
333f0 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20  ble is be being 
33400 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69  created or reini
33410 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  tialized..**.** 
33420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
33430 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
33440 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20  interface has a 
33450 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
33460 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
33470 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72  inter to a destr
33480 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43  uctor for the pC
33490 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c  lientData.  ^SQL
334a0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f  ite will.** invo
334b0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
334c0 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69  r function (if i
334d0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77  t is not NULL) w
334e0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f  hen SQLite.** no
334f0 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68   longer needs th
33500 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f  e pClientData po
33510 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c  inter.  ^The sql
33520 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
33530 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  le().** interfac
33540 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
33550 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
33560 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69  e_module_v2() wi
33570 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73  th a NULL.** des
33580 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  tructor..*/.int 
33590 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
335a0 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
335b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
335c0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
335d0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
335e0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
335f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
33600 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
33610 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
33620 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
33630 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
33640 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
33650 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
33660 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
33670 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20  entData         
33680 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
33690 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
336a0 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  nect */.);.int s
336b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
336c0 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  dule_v2(.  sqlit
336d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
336e0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
336f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
33700 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
33710 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
33720 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
33730 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
33740 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
33750 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
33760 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
33770 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
33780 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
33790 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20  lientData,      
337a0 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
337b0 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
337c0 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64  onnect */.  void
337d0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
337e0 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65  *)     /* Module
337f0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
33800 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  tion */.);../*.*
33810 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
33820 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e  ual Table Instan
33830 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ce Object.** KEY
33840 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
33850 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  tab.**.** Every 
33860 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
33870 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
33880 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
33890 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73  class.** of this
338a0 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72   object to descr
338b0 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72  ibe a particular
338c0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20   instance.** of 
338d0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
338e0 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c  le].  Each subcl
338f0 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
33900 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
33910 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
33920 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
33930 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54  ementation..** T
33940 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  he purpose of th
33950 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
33960 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
33970 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
33980 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20  re.** common to 
33990 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
339a0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
339b0 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65  * ^Virtual table
339c0 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
339d0 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
339e0 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
339f0 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
33a00 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
33a10 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
33a20 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
33a30 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
33a40 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
33a50 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
33a60 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
33a70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
33a80 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
33a90 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
33aa0 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
33ab0 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68  rMsg.  ^After th
33ac0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
33ad0 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
33ae0 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
33af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
33b00 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
33b10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
33b20 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
33b30 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
33b40 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
33b50 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
33b60 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
33b70 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
33b80 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
33b90 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
33ba0 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
33bb0 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
33bc0 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
33bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33be0 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
33bf0 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
33c00 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
33c10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
33c20 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
33c30 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
33c40 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
33c50 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
33c60 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
33c70 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
33c80 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
33c90 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
33ca0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
33cb0 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
33cc0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
33cd0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
33ce0 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  or {virtual tabl
33cf0 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20  e cursor}.**.** 
33d00 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
33d10 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
33d20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
33d30 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
33d40 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
33d50 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
33d60 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
33d70 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
33d80 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  e.** [virtual ta
33d90 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65  ble] and are use
33da0 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72  d.** to loop thr
33db0 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c  ough the virtual
33dc0 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73   table.  Cursors
33dd0 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
33de0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
33df0 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20  e3_module.xOpen 
33e00 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  | xOpen] method 
33e10 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  of the module an
33e20 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a  d are destroyed.
33e30 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ** by the [sqlit
33e40 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65  e3_module.xClose
33e50 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f   | xClose] metho
33e60 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  d.  Cursors are 
33e70 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  used.** by the [
33e80 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74  xFilter], [xNext
33e90 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c  ], [xEof], [xCol
33ea0 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69  umn], and [xRowi
33eb0 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  d] methods.** of
33ec0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
33ed0 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
33ee0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
33ef0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
33f00 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
33f10 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
33f20 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
33f30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
33f40 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
33f50 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
33f60 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
33f70 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
33f80 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
33f90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
33fa0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
33fb0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
33fc0 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
33fd0 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
33fe0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
33ff0 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
34000 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
34010 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
34020 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
34030 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
34040 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
34050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34060 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d  eclare The Schem
34070 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54  a Of A Virtual T
34080 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  able.**.** ^The 
34090 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
340a0 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
340b0 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61   of a.** [virtua
340c0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
340d0 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66  call this interf
340e0 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  ace.** to declar
340f0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
34100 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
34110 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
34120 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
34130 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
34140 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
34150 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
34160 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
34170 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
34180 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *zSQL);../*.** C
34190 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
341a0 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
341b0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
341c0 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c  .**.** ^(Virtual
341d0 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
341e0 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
341f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34200 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
34210 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64  using the [xFind
34220 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64  Function] method
34230 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
34240 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
34250 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20   .** But global 
34260 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
34270 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
34280 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
34290 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
342a0 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ded.)^.**.** ^(T
342b0 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
342c0 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
342d0 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
342e0 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
342f0 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
34300 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
34310 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
34320 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
34330 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
34340 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
34350 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
34360 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
34370 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d  .)^  ^The implem
34380 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
34390 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
343a0 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e  always causes an
343b0 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65   exception to be
343c0 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20   thrown.  So.** 
343d0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
343e0 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72   is not good for
343f0 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73   anything by its
34400 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a  elf.  Its only.*
34410 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20  * purpose is to 
34420 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72  be a placeholder
34430 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
34440 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
34450 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61  .** by a [virtua
34460 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74  l table]..*/.int
34470 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
34480 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
34490 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
344a0 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
344b0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
344c0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
344d0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
344e0 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
344f0 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
34500 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
34510 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
34520 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
34530 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
34540 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
34550 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
34560 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
34570 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
34580 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
34590 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
345a0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
345b0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
345c0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
345d0 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
345e0 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
345f0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
34600 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
34610 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
34620 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
34630 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
34640 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
34650 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
34660 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
34670 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
34680 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
34690 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  BLOB.** KEYWORDS
346a0 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
346b0 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
346c0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
346d0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
346e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
346f0 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
34700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
34710 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
34720 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
34730 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
34740 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20  .** ^Objects of 
34750 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
34760 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
34770 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
34780 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
34790 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
347a0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54  _close()]..** ^T
347b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
347c0 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
347d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
347e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
347f0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
34800 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
34810 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
34820 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
34830 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
34840 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
34850 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
34860 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
34870 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
34880 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
34890 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
348a0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
348b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
348c0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
348d0 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
348e0 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
348f0 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
34900 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
34910 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
34920 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
34930 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
34940 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
34950 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
34960 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
34970 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
34980 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
34990 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
349a0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
349b0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
349c0 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
349d0 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
349e0 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
349f0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  e>)^.**.** ^If t
34a00 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
34a10 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
34a20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
34a30 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
34a40 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
34a50 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20  cess. ^If it is 
34a60 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
34a70 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
34a80 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74  d access..** ^It
34a90 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
34aa0 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
34ab0 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
34ac0 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72  f an index or pr
34ad0 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f  imary .** key fo
34ae0 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b  r writing. ^If [
34af0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
34b00 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61  traints] are ena
34b10 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20  bled, it is .** 
34b20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
34b30 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
34b40 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
34b50 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20  [child key] for 
34b60 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  writing..**.** ^
34b70 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
34b80 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
34b90 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
34ba0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
34bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
34bc0 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
34bd0 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
34be0 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
34bf0 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65 72  ** appears after
34c00 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
34c10 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
34c20 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75  e is connected u
34c30 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a  sing [ATTACH]..*
34c40 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20  * ^For the main 
34c50 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
34c60 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
34c70 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e   is "main"..** ^
34c80 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
34c90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
34ca0 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
34cb0 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
34cc0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
34cd0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
34ce0 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64  e new [BLOB hand
34cf0 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  le] is written.*
34d00 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74  * to *ppBlob. Ot
34d10 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
34d20 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
34d30 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20  ned and *ppBlob 
34d40 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20  is set.** to be 
34d50 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29  a null pointer.)
34d60 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  ^.** ^This funct
34d70 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61  ion sets the [da
34d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34d90 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  n] error code an
34da0 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
34db0 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
34dc0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
34dd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
34de0 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74  msg()] and relat
34df0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e  ed.** functions.
34e00 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
34e10 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65  *ppBlob variable
34e20 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69   is always initi
34e30 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77  alized in a.** w
34e40 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  ay that makes it
34e50 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20   safe to invoke 
34e60 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34e70 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f  ose()] on *ppBlo
34e80 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  b.** regardless 
34e90 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f  of the success o
34ea0 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69  r failure of thi
34eb0 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
34ec0 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74 68   ^(If the row th
34ed0 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65  at a BLOB handle
34ee0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f   points to is mo
34ef0 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20  dified by an.** 
34f00 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54  [UPDATE], [DELET
34f10 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f  E], or by [ON CO
34f20 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66  NFLICT] side-eff
34f30 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ects.** then the
34f40 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
34f50 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72  marked as "expir
34f60 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ed"..** This is 
34f70 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75  true if any colu
34f80 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73  mn of the row is
34f90 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61   changed, even a
34fa0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72   column.** other
34fb0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68   than the one th
34fc0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
34fd0 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e   open on.)^.** ^
34fe0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
34ff0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
35000 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
35010 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
35020 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
35030 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
35040 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
35050 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
35060 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20  ]..** ^(Changes 
35070 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
35080 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
35090 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
350a0 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64  re not.** rolled
350b0 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70   back by the exp
350c0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42  iration of the B
350d0 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67  LOB.  Such chang
350e0 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  es will eventual
350f0 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20  ly.** commit if 
35100 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
35110 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
35120 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  pletion.)^.**.**
35130 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74   ^Use the [sqlit
35140 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
35150 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65   interface to de
35160 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
35170 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65   of.** the opene
35180 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69  d blob.  ^The si
35190 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79  ze of a blob may
351a0 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20   not be changed 
351b0 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  by this.** inter
351c0 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b  face.  Use the [
351d0 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d  UPDATE] SQL comm
351e0 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  and to change th
351f0 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62  e size of a.** b
35200 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lob..**.** ^The 
35210 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
35220 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73  roblob()] and [s
35230 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
35240 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66  roblob()] interf
35250 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20  aces.** and the 
35260 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c  built-in [zerobl
35270 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ob] SQL function
35280 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66   can be used, if
35290 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20   desired,.** to 
352a0 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c  create an empty,
352b0 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f   zero-filled blo
352c0 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65  b in which to re
352d0 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e  ad or write usin
352e0 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  g.** this interf
352f0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  ace..**.** To av
35300 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c  oid a resource l
35310 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20  eak, every open 
35320 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68  [BLOB handle] sh
35330 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a  ould eventually.
35340 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ** be released b
35350 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
35360 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
35370 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
35380 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20  e3_blob_open(.  
35390 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
353a0 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63  t char *zDb,.  c
353b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
353c0 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e,.  const char 
353d0 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69  *zColumn,.  sqli
353e0 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a  te3_int64 iRow,.
353f0 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73    int flags,.  s
35400 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70  qlite3_blob **pp
35410 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Blob.);../*.** C
35420 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41  API3REF: Close A
35430 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
35440 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70  ** ^Closes an op
35450 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
35460 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67  ..**.** ^Closing
35470 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61   a BLOB shall ca
35480 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  use the current 
35490 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63  transaction to c
354a0 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72  ommit.** if ther
354b0 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42  e are no other B
354c0 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67  LOBs, no pending
354d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
354e0 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a  ents, and the.**
354f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35500 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f  tion is in [auto
35510 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a  commit mode]..**
35520 20 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20   ^If any writes 
35530 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
35540 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
35550 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
35560 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
35570 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
35580 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
35590 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e  ..**.** ^(Closin
355a0 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
355b0 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
355c0 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
355d0 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
355e0 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
355f0 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
35600 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
35610 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
35620 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
35630 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68  .  Any errors th
35640 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a  at occur during.
35650 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72  ** closing are r
35660 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e  eported as a non
35670 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c  -zero return val
35680 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ue.)^.**.** ^(Th
35690 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
356a0 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79   unconditionally
356b0 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20  .  Even if this 
356c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a  routine returns.
356d0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  ** an error code
356e0 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74  , the BLOB is st
356f0 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a  ill closed.)^.**
35700 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
35710 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
35720 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73   null pointer (s
35730 75 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20  uch as would be 
35740 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61  returned.** by a
35750 20 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20   failed call to 
35760 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
35770 65 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d  en()]) is a harm
35780 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
35790 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
357a0 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
357b0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
357c0 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
357d0 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
357e0 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52  en BLOB.**.** ^R
357f0 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
35800 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
35810 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20  BLOB accessible 
35820 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63  via the .** succ
35830 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20  essfully opened 
35840 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
35850 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
35860 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63  nt.  ^The.** inc
35870 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f  remental blob I/
35880 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f  O routines can o
35890 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72  nly read or over
358a0 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67  writing existing
358b0 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74  .** blob content
358c0 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68  ; they cannot ch
358d0 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
358e0 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54   a blob..**.** T
358f0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
35900 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
35910 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
35920 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
35930 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
35940 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
35950 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
35960 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
35970 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
35980 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
35990 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
359a0 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
359b0 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
359c0 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
359d0 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
359e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
359f0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
35a00 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a  le behavior..*/.
35a10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
35a20 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
35a30 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
35a40 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
35a50 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
35a60 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
35a70 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
35a80 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
35a90 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
35aa0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
35ab0 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
35ac0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
35ad0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
35ae0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
35af0 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
35b00 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
35b10 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
35b20 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
35b30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66  )^.**.** ^If off
35b40 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
35b50 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
35b60 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
35b70 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
35b80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
35b90 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
35ba0 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e  data is read.  ^
35bb0 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20  If N or iOffset 
35bc0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
35bd0 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52  zero, [SQLITE_ER
35be0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
35bf0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
35c00 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69  read..** ^The si
35c10 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28  ze of the blob (
35c20 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
35c30 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
35c40 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
35c50 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
35c60 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
35c70 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
35c80 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
35c90 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20   ^An attempt to 
35ca0 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70  read from an exp
35cb0 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
35cc0 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
35cd0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
35ce0 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
35cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
35d00 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c  cess, sqlite3_bl
35d10 6f 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e  ob_read() return
35d20 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  s SQLITE_OK..** 
35d30 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65  Otherwise, an [e
35d40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
35d50 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
35d60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
35d70 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ed.)^.**.** This
35d80 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
35d90 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
35da0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
35db0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
35dc0 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
35dd0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
35de0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35df0 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
35e00 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
35e10 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
35e20 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
35e30 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
35e40 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
35e50 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
35e60 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
35e70 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
35e80 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
35e90 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
35ea0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
35eb0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
35ec0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35ed0 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74  _blob_read(sqlit
35ee0 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20  e3_blob *, void 
35ef0 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69  *Z, int N, int i
35f00 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
35f10 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20  CAPI3REF: Write 
35f20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42  Data Into A BLOB
35f30 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a   Incrementally.*
35f40 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
35f50 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77  ion is used to w
35f60 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61  rite data into a
35f70 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
35f80 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63  dle] from a.** c
35f90 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62  aller-supplied b
35fa0 75 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20  uffer. ^N bytes 
35fb0 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
35fc0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66  ed from the buff
35fd0 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  er Z.** into the
35fe0 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72   open BLOB, star
35ff0 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
36000 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49  Offset..**.** ^I
36010 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  f the [BLOB hand
36020 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  le] passed as th
36030 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
36040 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
36050 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28  for.** writing (
36060 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
36070 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
36080 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73  blob_open()] was
36090 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20   zero),.** this 
360a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
360b0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   [SQLITE_READONL
360c0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  Y]..**.** ^This 
360d0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c  function may onl
360e0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e  y modify the con
360f0 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f  tents of the BLO
36100 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  B; it is.** not 
36110 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72  possible to incr
36120 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ease the size of
36130 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68   a BLOB using th
36140 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f  is API..** ^If o
36150 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
36160 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74   less than N byt
36170 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
36180 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20  of the BLOB,.** 
36190 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
361a0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
361b0 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65  o data is writte
361c0 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20  n.  ^If N is.** 
361d0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
361e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
361f0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
36200 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
36210 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66  ..** The size of
36220 20 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68   the BLOB (and h
36230 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
36240 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
36250 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
36260 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
36270 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
36280 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
36290 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  face..**.** ^An 
362a0 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  attempt to write
362b0 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b   to an expired [
362c0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
362d0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
362e0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
362f0 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72  ITE_ABORT].  ^Wr
36300 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42  ites to the BLOB
36310 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a   that occurred.*
36320 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c  * before the [BL
36330 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72  OB handle] expir
36340 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65  ed are not rolle
36350 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a  d back by the.**
36360 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
36370 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67  he handle, thoug
36380 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73  h of course thos
36390 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a  e changes might.
363a0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65  ** have been ove
363b0 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
363c0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65  statement that e
363d0 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20  xpired the BLOB 
363e0 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20  handle.** or by 
363f0 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e  other independen
36400 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  t statements..**
36410 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
36420 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  , sqlite3_blob_w
36430 72 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53  rite() returns S
36440 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68  QLITE_OK..** Oth
36450 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72  erwise, an  [err
36460 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
36470 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
36480 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
36490 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
364a0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
364b0 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
364c0 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
364d0 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
364e0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
364f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
36500 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
36510 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
36520 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
36530 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
36540 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
36550 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
36560 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
36570 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
36580 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
36590 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
365a0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
365b0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
365c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
365d0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a  _blob_read()]..*
365e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
365f0 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33  ob_write(sqlite3
36600 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76  _blob *, const v
36610 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69  oid *z, int n, i
36620 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
36630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
36640 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
36650 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
36660 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
36670 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
36680 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
36690 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
366a0 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
366b0 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
366c0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
366d0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
366e0 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c  Most SQLite buil
366f0 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a  ds come with a.*
36700 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74  * single default
36710 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70   VFS that is app
36720 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65  ropriate for the
36730 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
36740 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e  ** New VFSes can
36750 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
36760 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65  nd existing VFSe
36770 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73  s can be unregis
36780 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f  tered..** The fo
36790 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
367a0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e  es are provided.
367b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
367c0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
367d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
367e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
367f0 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61  VFS given its na
36800 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72  me..** ^Names ar
36810 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65  e case sensitive
36820 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20  ..** ^Names are 
36830 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
36840 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
36850 2a 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  * ^If there is n
36860 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20  o match, a NULL 
36870 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
36880 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73  ned..** ^If zVfs
36890 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
368a0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  n the default VF
368b0 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  S is returned..*
368c0 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20  *.** ^New VFSes 
368d0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77  are registered w
368e0 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  ith sqlite3_vfs_
368f0 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e  register()..** ^
36900 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63  Each new VFS bec
36910 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74  omes the default
36920 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65   VFS if the make
36930 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74  Dflt flag is set
36940 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56  ..** ^The same V
36950 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  FS can be regist
36960 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
36970 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75  mes without inju
36980 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20  ry..** ^To make 
36990 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
369a0 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
369b0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
369c0 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
369d0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
369e0 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
369f0 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
36a00 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
36a10 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
36a20 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
36a30 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
36a40 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
36a50 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
36a60 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
36a70 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
36a80 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
36a90 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
36aa0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
36ab0 20 5e 55 6e 72 65 67 69 73 74 65 72 20 61 20 56   ^Unregister a V
36ac0 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
36ad0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
36ae0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
36af0 2a 2a 20 5e 28 49 66 20 74 68 65 20 64 65 66 61  ** ^(If the defa
36b00 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67  ult VFS is unreg
36b10 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72  istered, another
36b20 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61   VFS is chosen a
36b30 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  s.** the default
36b40 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f  .  The choice fo
36b50 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73  r the new VFS is
36b60 20 61 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f   arbitrary.)^.*/
36b70 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71  .sqlite3_vfs *sq
36b80 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63  lite3_vfs_find(c
36b90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e  onst char *zVfsN
36ba0 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ame);.int sqlite
36bb0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73  3_vfs_register(s
36bc0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
36bd0 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20   makeDflt);.int 
36be0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
36bf0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
36c00 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  fs*);../*.** CAP
36c10 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a  I3REF: Mutexes.*
36c20 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
36c30 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
36c40 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
36c50 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
36c60 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74  zation. Though t
36c70 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
36c80 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
36c90 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
36ca0 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
36cb0 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
36cc0 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
36cd0 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
36ce0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
36cf0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
36d00 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
36d10 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
36d20 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
36d30 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
36d40 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
36d50 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
36d60 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
36d70 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
36d80 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
36d90 69 6d 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  ime.  ^(The foll
36da0 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65  owing.** impleme
36db0 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61  ntations are ava
36dc0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51  ilable in the SQ
36dd0 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a  Lite core:.**.**
36de0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20   <ul>.** <li>   
36df0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
36e00 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
36e10 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a  E_MUTEX_PTHREAD.
36e20 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
36e30 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c  _MUTEX_W32.** <l
36e40 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
36e50 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29  X_NOOP.** </ul>)
36e60 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  ^.**.** ^The SQL
36e70 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69  ITE_MUTEX_NOOP i
36e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
36e90 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e   a set of routin
36ea0 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  es.** that does 
36eb0 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20  no real locking 
36ec0 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61  and is appropria
36ed0 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a  te for use in.**
36ee0 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64   a single-thread
36ef0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  ed application. 
36f00 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54   ^The SQLITE_MUT
36f10 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54  EX_OS2,.** SQLIT
36f20 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c  E_MUTEX_PTHREAD,
36f30 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
36f40 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61  X_W32 implementa
36f50 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70  tions.** are app
36f60 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
36f70 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20   on OS/2, Unix, 
36f80 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a  and Windows..**.
36f90 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69  ** ^(If SQLite i
36fa0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
36fb0 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  the SQLITE_MUTEX
36fc0 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65  _APPDEF preproce
36fd0 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65  ssor.** macro de
36fe0 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53  fined (with "-DS
36ff0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44  QLITE_MUTEX_APPD
37000 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20  EF=1"), then no 
37010 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
37020 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75  ntation is inclu
37030 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ded with the lib
37040 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61  rary. In this ca
37050 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  se the.** applic
37060 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
37070 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78  y a custom mutex
37080 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37090 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
370a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
370b0 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65  X] option of the
370c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
370d0 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  ) function.** be
370e0 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c  fore calling sql
370f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
37100 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70  ) or any other p
37110 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a  ublic sqlite3_.*
37120 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
37130 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
37140 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a  itialize().)^.**
37150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37160 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72  _mutex_alloc() r
37170 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73  outine allocates
37180 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20   a new.** mutex 
37190 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
371a0 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66  inter to it. ^If
371b0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
371c0 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74  .** that means t
371d0 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c  hat a mutex coul
371e0 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74  d not be allocat
371f0 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  ed.  ^SQLite.** 
37200 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20  will unwind its 
37210 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e  stack and return
37220 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68   an error.  ^(Th
37230 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
37240 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
37250 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66  lloc() is one of
37260 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
37270 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20  onstants:.**.** 
37280 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
37290 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
372a0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
372b0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
372c0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
372d0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
372e0 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  TER.** <li>  SQL
372f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37300 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  _MEM.** <li>  SQ
37310 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37320 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20  C_MEM2.** <li>  
37330 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
37340 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e  TIC_PRNG.** <li>
37350 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
37360 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69  TATIC_LRU.** <li
37370 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
37380 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c  STATIC_LRU2.** <
37390 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  /ul>)^.**.** ^Th
373a0 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73  e first two cons
373b0 74 61 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55  tants (SQLITE_MU
373c0 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
373d0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
373e0 49 56 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71  IVE).** cause sq
373f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37400 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
37410 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e   a new mutex.  ^
37420 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
37430 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
37440 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
37450 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
37460 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
37470 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
37480 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
37490 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20  is used..** The 
374a0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
374b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
374c0 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73  ed to make a dis
374d0 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
374e0 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  een SQLITE_MUTEX
374f0 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53  _RECURSIVE and S
37500 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
37510 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
37520 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51  ot want to.  ^SQ
37530 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72  Lite will only r
37540 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69  equest a recursi
37550 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63  ve mutex in.** c
37560 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65  ases where it re
37570 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20  ally needs one. 
37580 20 5e 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f   ^If a faster no
37590 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  n-recursive mute
375a0 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
375b0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
375c0 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61   on the host pla
375d0 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78  tform, the mutex
375e0 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69   subsystem.** mi
375f0 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20  ght return such 
37600 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f  a mutex in respo
37610 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55  nse to SQLITE_MU
37620 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20  TEX_FAST..**.** 
37630 5e 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77  ^The other allow
37640 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
37650 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
37660 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67  lloc() (anything
37670 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53   other.** than S
37680 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
37690 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
376a0 58 5f 52 45 43 55 52 53 49 56 45 29 20 65 61 63  X_RECURSIVE) eac
376b0 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f  h return.** a po
376c0 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69  inter to a stati
376d0 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75  c preexisting mu
376e0 74 65 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69  tex.  ^Six stati
376f0 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
37700 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
37710 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
37720 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
37730 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
37740 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
37750 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
37760 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
37770 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
37780 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
37790 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
377a0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
377b0 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
377c0 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
377d0 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
377e0 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
377f0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
37800 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
37810 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
37820 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
37830 5e 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e  ^Note that if on
37840 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63  e of the dynamic
37850 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72   mutex parameter
37860 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  s (SQLITE_MUTEX_
37870 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54  FAST.** or SQLIT
37880 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
37890 45 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20  E) is used then 
378a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
378b0 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  loc().** returns
378c0 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74   a different mut
378d0 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ex on every call
378e0 2e 20 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20  .  ^But for the 
378f0 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
37900 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
37910 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
37920 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
37930 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
37940 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
37950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37960 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
37970 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f  ) routine deallo
37980 63 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73  cates a previous
37990 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ly.** allocated 
379a0 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20  dynamic mutex.  
379b0 5e 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66  ^SQLite is caref
379c0 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ul to deallocate
379d0 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69   every.** dynami
379e0 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20  c mutex that it 
379f0 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20  allocates.  The 
37a00 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20  dynamic mutexes 
37a10 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a  must not be in.*
37a20 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20  * use when they 
37a30 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
37a40 20 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20    Attempting to 
37a50 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61  deallocate a sta
37a60 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73  tic.** mutex res
37a70 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
37a80 64 20 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51  d behavior.  ^SQ
37a90 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c  Lite never deall
37aa0 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74  ocates.** a stat
37ab0 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20  ic mutex..**.** 
37ac0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
37ad0 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
37ae0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
37af0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
37b00 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
37b10 61 20 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e  a mutex.  ^If an
37b20 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20  other thread is 
37b30 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74  already within t
37b40 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c  he mutex,.** sql
37b50 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
37b60 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e  () will block an
37b70 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
37b80 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72  try() will retur
37b90 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  n.** SQLITE_BUSY
37ba0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
37bb0 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65  mutex_try() inte
37bc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53  rface returns [S
37bd0 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f  QLITE_OK].** upo
37be0 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74  n successful ent
37bf0 72 79 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63  ry.  ^(Mutexes c
37c00 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
37c10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
37c20 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e  URSIVE can be en
37c30 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
37c40 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
37c50 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73   thread..** In s
37c60 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
37c70 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
37c80 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
37c90 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
37ca0 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
37cb0 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
37cc0 65 72 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20  er.)^  ^(If the 
37cd0 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65  same thread trie
37ce0 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f  s to enter any o
37cf0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
37d00 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20  mutex more than 
37d10 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69  once, the behavi
37d20 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
37d30 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
37d40 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a  never exhibit.**
37d50 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69   such behavior i
37d60 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66  n its own use of
37d70 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a   mutexes.)^.**.*
37d80 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73  * ^(Some systems
37d90 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57   (for example, W
37da0 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f  indows 95) do no
37db0 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70  t support the op
37dc0 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  eration.** imple
37dd0 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65  mented by sqlite
37de0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20  3_mutex_try().  
37df0 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73  On those systems
37e00 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  , sqlite3_mutex_
37e10 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c  try().** will al
37e20 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49  ways return SQLI
37e30 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51  TE_BUSY.  The SQ
37e40 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65  Lite core only e
37e50 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69  ver uses.** sqli
37e60 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
37e70 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69  as an optimizati
37e80 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63  on so this is ac
37e90 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f  ceptable behavio
37ea0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
37eb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
37ec0 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78  ave() routine ex
37ed0 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74  its a mutex that
37ee0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
37ef0 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
37f00 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20  e same thread.  
37f10 20 5e 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a   ^(The behavior.
37f20 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ** is undefined 
37f30 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20  if the mutex is 
37f40 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  not currently en
37f50 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  tered by the.** 
37f60 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f  calling thread o
37f70 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  r is not current
37f80 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53  ly allocated.  S
37f90 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
37fa0 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e  ver do either.)^
37fb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
37fc0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
37fd0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
37fe0 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  , sqlite3_mutex_
37ff0 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c  try(), or.** sql
38000 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
38010 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38020 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74  nter, then all t
38030 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hree routines.**
38040 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70   behave as no-op
38050 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
38060 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  o: [sqlite3_mute
38070 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73  x_held()] and [s
38080 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
38090 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  held()]..*/.sqli
380a0 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74  te3_mutex *sqlit
380b0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69  e3_mutex_alloc(i
380c0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
380d0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c  3_mutex_free(sql
380e0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
380f0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
38100 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d  _enter(sqlite3_m
38110 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
38120 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71  te3_mutex_try(sq
38130 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
38140 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
38150 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f  x_leave(sqlite3_
38160 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
38170 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
38180 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
38190 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
381a0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
381b0 72 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c  re defines the l
381c0 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65  ow-level routine
381d0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c  s.** used to all
381e0 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75  ocate and use mu
381f0 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75  texes..**.** Usu
38200 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c  ally, the defaul
38210 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  t mutex implemen
38220 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64  tations provided
38230 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a   by SQLite are.*
38240 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f  * sufficient, ho
38250 77 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68  wever the user h
38260 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66  as the option of
38270 20 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20   substituting a 
38280 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d  custom.** implem
38290 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65  entation for spe
382a0 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d  cialized deploym
382b0 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20  ents or systems 
382c0 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65  for which SQLite
382d0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  .** does not pro
382e0 76 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20  vide a suitable 
382f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
38300 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68  In this case, th
38310 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65  e user.** create
38320 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20  s and populates 
38330 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
38340 68 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f  his structure to
38350 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69   pass.** to sqli
38360 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f  te3_config() alo
38370 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ng with the [SQL
38380 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
38390 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64  ] option..** Add
383a0 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e  itionally, an in
383b0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
383c0 74 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20  tructure can be 
383d0 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75  used as an.** ou
383e0 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68  tput variable wh
383f0 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20  en querying the 
38400 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63  system for the c
38410 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20  urrent mutex.** 
38420 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
38430 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
38440 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
38450 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  X] option..**.**
38460 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74   ^The xMutexInit
38470 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
38480 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
38490 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
384a0 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
384b0 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  m initialization
384c0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
384d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e  initialize() fun
384e0 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78  ction..** ^The x
384f0 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e  MutexInit routin
38500 65 20 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51  e is calle by SQ
38510 4c 69 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63  Lite exactly onc
38520 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66  e for each.** ef
38530 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
38540 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
38550 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ize()]..**.** ^T
38560 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74  he xMutexEnd met
38570 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
38580 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
38590 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
385a0 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68  art of system sh
385b0 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71  utdown by the sq
385c0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
385d0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a   function. The.*
385e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
385f0 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
38600 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72  is expected to r
38610 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74  elease all outst
38620 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72  anding.** resour
38630 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ces obtained by 
38640 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64  the mutex method
38650 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
38660 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20  , especially.** 
38670 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62  those obtained b
38680 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74  y the xMutexInit
38690 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 78   method.  ^The x
386a0 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e  MutexEnd().** in
386b0 74 65 72 66 61 63 65 20 69 73 20 69 6e 76 6f 6b  terface is invok
386c0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  ed exactly once 
386d0 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  for each call to
386e0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
386f0 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  wn()]..**.** ^(T
38700 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76  he remaining sev
38710 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  en methods defin
38720 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
38730 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f  ture (xMutexAllo
38740 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65  c,.** xMutexFree
38750 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78  , xMutexEnter, x
38760 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78  MutexTry, xMutex
38770 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c  Leave, xMutexHel
38780 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e  d and.** xMutexN
38790 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e  otheld) implemen
387a0 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  t the following 
387b0 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70  interfaces (resp
387c0 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a  ectively):.**.**
387d0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
387e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
387f0 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  alloc()] </li>.*
38800 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
38810 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d  e3_mutex_free()]
38820 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
38830 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
38840 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a  _enter()] </li>.
38850 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
38860 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d  te3_mutex_try()]
38870 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
38880 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
38890 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a  _leave()] </li>.
388a0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
388b0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
388c0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
388d0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
388e0 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c  x_notheld()] </l
388f0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
38900 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  .** The only dif
38910 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20  ference is that 
38920 74 68 65 20 70 75 62 6c 69 63 2