/ Hex Artifact Content
Login

Artifact 8da2897e3c9b251b29aa48d11bfb1f30f1de0733:


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 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
41d0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
41e0: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
41f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4200: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4210: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4220: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4230: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4250: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4260: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4280: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4290: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42a0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42b0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
42c0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
42d0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
42e0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
42f0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4310: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4320: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4330: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4360: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4370: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4380: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4390: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43a0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43b0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
43c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
43f0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4400: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4410: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4420: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4430: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4440: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4460: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4470: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4480: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4490: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44a0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44b0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
44c0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
44f0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4500: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4510: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4520: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4530: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4540: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4550: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4560: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4570: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4580: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4590: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45a0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45b0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
45c0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
45d0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
45e0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
45f0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4620: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4630: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4640: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4650: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4660: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4670: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4680: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4690: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46a0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46b0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
46c0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
46d0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
46e0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
46f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4700: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4710: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4720: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4730: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4740: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4750: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4760: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4770: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4780: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4790: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47a0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47b0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
47c0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
47d0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
47e0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
47f0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4800: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4810: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4820: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4830: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4840: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4850: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4860: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4870: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4880: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4890: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48a0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48b0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
48c0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
48d0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
48e0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
48f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4900: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4910: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4930: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4940: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4950: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4960: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4970: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4980: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4990: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49a0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49b0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
49c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
49d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
49e0: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
49f0: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a00: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a10: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a20: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a30: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a40: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a50: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4a60: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4a70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4a80: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4a90: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4aa0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4ab0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4ac0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ae0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4af0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b00: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b40: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4b60: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4b70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b80: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ba0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4bc0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4be0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4bf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c00: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c40: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c60: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4c70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c80: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ca0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cc0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4ce0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4cf0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d00: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d20: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d40: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4d60: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4da0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4de0: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e20: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4e60: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ea0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f20: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
4fe0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
4ff0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5000: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5010: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5020: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5030: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5040: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5050: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5060: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5070: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5080: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
5090: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
50a0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
50b0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
50c0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
50d0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
50e0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
50f0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5100: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5110: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5120: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5130: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5140: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5150: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5160: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5170: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5190: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
51a0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
51b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
51c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
51d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
51e0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
51f0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5200: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5210: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5220: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5230: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5240: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5250: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5260: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5280: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5290: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
52a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
52c0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
52d0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
52e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5300: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5310: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5320: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5340: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5350: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5360: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5370: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5380: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5390: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
53a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
53c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
53d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
53e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5400: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5410: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5420: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5440: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5450: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5460: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5470: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5480: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5490: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
54a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
54c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
54d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
54e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5500: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5510: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5520: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5530: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5540: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
5550: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
5560: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
5570: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5580: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5590: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
55a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
55b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
55c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
55d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
55e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
55f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
5600: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
5610: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5620: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
5640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5650: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
5660: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
5670: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5690: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
56a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
56b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
56c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
56d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
56e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
56f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5700: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
5710: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
5720: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
5730: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
5740: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5750: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5760: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5770: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5780: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5790: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
57a0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
57b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
57c0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
57d0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
57e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
57f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5800: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5810: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
5820: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5840: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5850: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5860: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5870: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5880: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5890: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
58a0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
58b0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
58c0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
58f0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5900: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5910: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
5920: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
5930: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
5940: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5950: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5960: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5970: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5980: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5990: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
59a0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
59b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
59c0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
59d0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
59e0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
59f0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5a00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5a10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a20: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5a30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5a40: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5a50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5a60: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
5a70: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a90: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5aa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ab0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5ac0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ad0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5ae0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5af0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b00: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b20: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b50: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5b60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b70: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
5b80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5bc0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5bd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5be0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
5bf0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c10: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5c20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c30: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5c40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5c50: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
5c60: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c80: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
5c90: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
5ca0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
5cb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5cc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5cd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5ce0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5cf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5d00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5d10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5d20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5d30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5d40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5d50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5d60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5d90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5da0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5db0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5dc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5dd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5df0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5e20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5e30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5e40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5e50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5e60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5e70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5e80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5e90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5ea0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5eb0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5ec0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5ed0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5ee0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5ef0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5f00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5f10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5f20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5f30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5f40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5f50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5f60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5f70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5f80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5f90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5fa0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5fb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5fc0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5fd0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5fe0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ff0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6000: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6010: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6020: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6030: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6040: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6050: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6060: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6070: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6080: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
60b0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
60c0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
60d0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
60e0: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
60f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6100: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6110: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6120: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6130: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6140: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6150: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6160: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6170: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6180: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6190: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
61a0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
61b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
61c0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
61d0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
61e0: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
61f0: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6200: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6210: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
6220: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
6230: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
6240: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
6250: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
6260: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
6270: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6280: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6290: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
62a0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
62b0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
62c0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
62d0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
62e0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
62f0: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6300: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6310: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
6320: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
6330: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
6340: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6350: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
6360: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6370: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
63b0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
63c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
63d0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
63e0: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
63f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6400: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6410: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
6420: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
6430: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
6440: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
6450: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
6460: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
6470: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6480: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6490: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
64a0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
64b0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
64c0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
64d0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
64e0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
64f0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6500: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6510: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6520: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6530: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6540: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
6550: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
6560: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6570: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6580: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
65a0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
65b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65c0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
65d0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
65e0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
65f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6600: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6610: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6620: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
6630: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
6640: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
6650: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
6660: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
6670: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6680: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6690: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
66a0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
66b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
66c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
66d0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
66e0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
66f0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6700: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6710: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6720: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6730: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6740: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6750: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6760: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6780: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6790: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
67a0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
67b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
67c0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
67d0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
67e0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
67f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6800: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6810: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
6820: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
6830: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6840: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6850: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6860: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6870: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6880: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
6890: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
68a0: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
68b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
68c0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
68d0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
68e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
68f0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6900: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6910: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6920: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6930: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6940: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6950: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6960: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6970: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6980: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6990: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
69a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
69b0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
69c0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
69d0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
69e0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
69f0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6a00: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6a10: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6a20: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6a30: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6a40: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6a50: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6a60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6a70: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6a80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6a90: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6ab0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6ad0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6ae0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6af0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6b00: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6b10: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6b20: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6b30: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6b40: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6b50: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6b60: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6b70: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6b80: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6b90: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6ba0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6bb0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6bc0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6bd0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6be0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6bf0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6c00: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6c10: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6c20: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6c30: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6c40: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6c50: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6c60: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6c70: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6c80: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6c90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6ca0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6cb0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6cc0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6cd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6ce0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6cf0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6d00: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6d10: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6d20: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6d30: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6d40: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6d50: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6d60: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6d70: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6d80: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6d90: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6da0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6db0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6dc0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6dd0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6de0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6df0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6e00: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6e10: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6e20: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6e30: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6e40: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6e50: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6e60: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6e70: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6e80: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6e90: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6ea0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6eb0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6ec0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6ed0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6ee0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6ef0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6f00: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6f10: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6f20: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6f30: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6f40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6f50: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6f60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6f70: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6f80: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6f90: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6fa0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
6fb0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6fc0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
6fd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
6fe0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
6ff0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7000: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7010: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7020: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7030: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7040: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7050: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7060: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7070: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7080: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7090: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
70a0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
70b0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
70c0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
70d0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
70e0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
70f0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7100: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7110: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7120: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7130: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7140: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7150: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7160: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7180: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
71a0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
71b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71c0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
71d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71e0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7210: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7220: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7240: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7250: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7260: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7270: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7280: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
72a0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
72b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72c0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
72d0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
72e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
72f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7300: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7310: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7320: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7330: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7340: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7350: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7360: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7370: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7380: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7390: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
73a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
73b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
73c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
73d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
73e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7400: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7410: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7420: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7430: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7440: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7450: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7460: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7470: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7480: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7490: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
74a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
74b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
74c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
74d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
74e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
74f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7500: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7510: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7520: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7530: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7540: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7550: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7560: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7570: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7580: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7590: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
75a0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
75b0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
75c0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
75d0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
75e0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
75f0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7600: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7610: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7620: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7630: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7660: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7670: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7680: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7690: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
76a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
76b0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
76c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
76d0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
76e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
76f0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7700: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7710: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7720: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7730: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7740: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7750: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7760: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7770: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7780: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7790: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
77a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
77b0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
77c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
77d0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
77e0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
77f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7800: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7820: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
7830: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
7840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7850: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
7860: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
7870: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7880: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7890: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
78a0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
78b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78c0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
78d0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
78e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7900: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7910: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
7920: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
7930: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7940: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
7950: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
7960: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
7970: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7980: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7990: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
79a0: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
79b0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
79c0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
79d0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
79e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
79f0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7a00: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7a10: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7a20: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7a30: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7a40: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7a50: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7a60: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7a80: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7a90: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7aa0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7ab0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7ac0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7ad0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7ae0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7af0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7b00: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7b10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7b20: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7b30: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7b50: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7b60: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7b70: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7b80: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7b90: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7ba0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7bb0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7bc0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7bd0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7be0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7bf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7c00: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7c10: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7c20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c30: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7c40: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7c50: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7c60: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7c70: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7c80: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7c90: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7ca0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7cb0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7cc0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7cd0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7ce0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7cf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7d00: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
7d10: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
7d20: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
7d30: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
7d40: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
7d50: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7d60: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7d70: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7d80: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7d90: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7da0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7db0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7dc0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7dd0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7de0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7df0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7e00: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7e10: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7e20: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7e30: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7e40: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7e50: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7e60: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7e70: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
7e80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
7e90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
7ea0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
7eb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
7ec0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
7ed0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
7ee0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7ef0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
7f00: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
7f10: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
7f20: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
7f30: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
7f40: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
7f50: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
7f60: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
7f70: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
7f80: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
7f90: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
7fa0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
7fb0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
7fc0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
7fd0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
7fe0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
7ff0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8000: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8010: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8020: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8030: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8040: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8050: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
8060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
8070: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8090: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
80a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
80b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
80c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
80d0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
80e0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
80f0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8100: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8110: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8120: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8130: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8140: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
8150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8160: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8170: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8180: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8190: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
81a0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
81b0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
81c0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
81d0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
81e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
81f0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8200: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8210: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8220: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8230: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8240: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8250: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8260: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8270: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8280: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8290: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
82a0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
82b0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
82c0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
82d0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
82e0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
82f0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8310: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8320: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8330: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8340: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8350: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8360: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8370: 65 63 69 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  ecilized VFSes.*
8380: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8390: 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69  e it.  .*/.#defi
83a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
83b0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
83c0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
83d0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
83e0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
83f0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
8400: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8410: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
8420: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
8430: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
8440: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8450: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
8460: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
8470: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8480: 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69  ZE       6.#defi
8490: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
84a0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
84b0: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
84c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
84d0: 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  TTED     8.../*.
84e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
84f0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
8500: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
8510: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
8520: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
8530: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
8540: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
8550: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
8560: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
8570: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
8580: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
8590: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
85a0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
85b0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
85c0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
85d0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
85e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
85f0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
8600: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
8610: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
8620: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
8630: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
8640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
8650: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
8660: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8670: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
8680: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
8690: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
86a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
86b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
86c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
86d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
86e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
86f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8700: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8710: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8720: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8730: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8740: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8750: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8760: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8770: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8780: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8790: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
87a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
87b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
87c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
87d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
87e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
87f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8800: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8810: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8820: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8830: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8840: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8850: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8860: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8870: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8880: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8890: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
88a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
88b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
88c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
88d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
88e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
88f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8900: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8910: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8920: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8930: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8940: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8950: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8960: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8970: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8980: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8990: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
89a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
89b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
89c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
89d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
89e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
89f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8a00: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8a10: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8a20: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8a30: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8a40: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8a50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8a60: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8a70: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8a80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8a90: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
8aa0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8ab0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
8ac0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
8ad0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
8ae0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
8af0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8b00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8b10: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8b20: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8b30: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8b40: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8b50: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8b60: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8b70: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8b80: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8b90: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8ba0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
8bb0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
8bc0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
8bd0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
8be0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
8bf0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8c00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8c10: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8c20: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8c30: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8c40: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8c50: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8c60: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8c70: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8c80: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8c90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8ca0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8cb0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8cc0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8cd0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
8ce0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
8cf0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8d00: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8d10: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8d20: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8d30: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8d40: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8d50: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8d60: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8d70: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8d80: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8d90: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
8da0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
8db0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
8dc0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
8dd0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
8de0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
8df0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8e00: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8e10: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8e20: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8e30: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8e40: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8e50: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8e60: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8e70: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8e80: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8e90: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
8ea0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
8eb0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
8ec0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
8ed0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8ee0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
8ef0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8f00: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8f10: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8f20: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8f30: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8f40: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8f50: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8f60: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8f70: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8f80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8f90: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
8fa0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
8fb0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8fc0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
8fd0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8fe0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
8ff0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
9000: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
9010: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9020: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
9030: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
9040: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
9050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
9060: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
9070: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
9080: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
9090: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
90a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
90b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
90c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
90d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
90e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
90f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
9100: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9110: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
9120: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
9130: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
9140: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
9150: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
9160: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
9170: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
9180: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
9190: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
91a0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
91b0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
91c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
91d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
91e0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
91f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
9200: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9210: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
9220: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
9230: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
9240: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
9250: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9260: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
9270: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9280: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
9290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
92a0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
92b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
92c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
92d0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
92e0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
92f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9300: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
9310: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
9320: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
9330: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
9340: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
9350: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
9360: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
9370: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
9380: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
9390: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
93a0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
93b0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
93c0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
93d0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
93e0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
93f0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
9400: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
9410: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
9420: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
9430: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
9440: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
9450: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
9460: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
9470: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9480: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
9490: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
94a0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
94b0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
94c0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
94d0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
94e0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
94f0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
9500: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
9510: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
9520: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
9530: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
9540: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
9550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9560: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
9570: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
9580: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
9590: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
95a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
95b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
95c0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
95d0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
95e0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
95f0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
9600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
9610: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
9620: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
9630: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
9640: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
9650: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
9660: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
9670: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
9680: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
9690: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
96a0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
96b0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
96c0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
96d0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
96e0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
96f0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9700: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9710: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9720: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9730: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9740: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9750: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9760: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9770: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9780: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9790: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
97a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
97b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
97c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
97d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
97e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
97f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9800: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9810: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9820: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9830: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9840: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9850: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9860: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9870: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9880: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9890: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
98a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
98b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
98c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
98d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
98e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
98f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9900: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9910: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9920: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9930: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9940: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9950: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9960: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9980: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9990: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
99a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
99b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
99c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
99d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
99e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
99f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9a00: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9a10: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9a20: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9a30: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9a40: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9a50: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9a60: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9a70: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9a80: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9a90: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
9aa0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
9ab0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
9ac0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
9ad0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
9ae0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
9af0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9b00: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9b10: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9b20: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9b30: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9b40: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9b50: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9b60: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9b70: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9b80: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9b90: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
9ba0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
9bb0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
9bc0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
9bd0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
9be0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
9bf0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9c00: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9c10: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9c20: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9c30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9c40: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9c50: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9c60: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9c70: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9c80: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9c90: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
9ca0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
9cb0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
9cc0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
9cd0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
9ce0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
9cf0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9d00: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9d10: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9d20: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9d30: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9d40: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9d50: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9d60: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9d70: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9d80: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9d90: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
9da0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
9db0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
9dc0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
9dd0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
9de0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
9df0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9e00: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9e10: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9e20: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9e30: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9e40: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9e50: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9e60: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9e70: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9e80: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9e90: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
9ea0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
9eb0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
9ec0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
9ed0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
9ee0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
9ef0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9f00: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9f10: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9f20: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9f30: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9f40: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9f50: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9f60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9f70: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9f80: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9f90: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
9fa0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
9fb0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
9fc0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9fd0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
9fe0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
9ff0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
a000: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
a010: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
a020: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
a030: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
a040: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
a050: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
a060: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
a070: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
a080: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
a090: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
a0a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
a0b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
a0c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
a0d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
a0e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
a0f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
a100: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
a110: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
a120: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
a130: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
a140: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
a150: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
a160: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
a170: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
a180: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
a190: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
a1a0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
a1b0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
a1c0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
a1d0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
a1e0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
a1f0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
a200: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
a210: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
a220: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
a230: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
a240: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
a250: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
a260: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
a270: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
a280: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
a290: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
a2a0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
a2b0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
a2c0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
a2d0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
a2e0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
a2f0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
a300: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
a310: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
a320: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
a330: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
a340: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
a350: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
a360: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
a370: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
a380: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
a390: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
a3a0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
a3b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
a3c0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
a3d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
a3e0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
a3f0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
a400: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
a410: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
a420: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
a430: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
a440: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
a450: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
a460: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
a470: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
a480: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a490: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
a4a0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
a4b0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
a4c0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
a4d0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
a4e0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
a4f0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
a500: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
a510: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
a520: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
a530: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
a540: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
a550: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
a560: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
a570: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
a580: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
a590: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
a5a0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
a5b0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
a5c0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
a5d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a5e0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
a5f0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
a600: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
a610: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
a620: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
a630: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
a640: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
a650: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a660: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
a670: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
a680: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
a690: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
a6a0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
a6b0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
a6c0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
a6d0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
a6e0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
a6f0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a700: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a710: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a720: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a730: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a740: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a750: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a760: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a770: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a780: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a790: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a7a0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a7b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a7c0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a7d0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a7e0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a7f0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a800: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a810: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a820: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a830: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a840: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a850: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a860: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a870: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a880: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a890: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a8a0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a8b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a8c0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a8d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a8e0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a8f0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a900: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a910: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a920: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a930: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a940: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a950: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a960: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a970: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
a980: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
a990: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
a9a0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
a9b0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
a9c0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
a9d0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
a9e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a9f0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
aa00: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
aa10: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
aa20: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
aa30: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
aa40: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
aa50: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
aa60: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
aa70: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
aa80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
aa90: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
aaa0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
aab0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
aac0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
aad0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
aae0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
aaf0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
ab00: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
ab10: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
ab20: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
ab30: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
ab40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
ab50: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
ab60: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
ab70: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ab80: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
ab90: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
aba0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
abb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
abc0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
abd0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
abe0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
abf0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ac00: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
ac10: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
ac20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
ac30: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
ac40: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
ac50: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
ac60: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
ac70: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
ac80: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ac90: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
aca0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
acb0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
acc0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
acd0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
ace0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
acf0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
ad00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ad10: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
ad20: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
ad30: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
ad40: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
ad50: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
ad60: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
ad70: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
ad80: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
ad90: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
ada0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
adb0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
adc0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
add0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
ade0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
adf0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
ae00: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
ae10: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
ae20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
ae30: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
ae40: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
ae50: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
ae60: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
ae70: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
ae80: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
ae90: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
aea0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
aeb0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
aec0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
aed0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
aee0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
aef0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
af00: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
af10: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
af20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
af30: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
af40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
af50: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
af60: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
af70: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
af80: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
af90: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
afa0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
afb0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
afc0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
afd0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
afe0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
aff0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
b000: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
b010: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
b020: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
b030: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
b040: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
b050: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
b060: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
b070: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
b080: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
b090: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
b0a0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
b0b0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
b0c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
b0d0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
b0e0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
b0f0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
b100: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
b110: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
b120: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
b130: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
b140: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
b150: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
b160: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
b170: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
b180: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
b190: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
b1a0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
b1b0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
b1c0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
b1d0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
b1e0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
b1f0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
b200: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
b210: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
b220: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
b230: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
b240: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
b250: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
b260: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
b270: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
b280: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
b290: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b2a0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
b2b0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
b2c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
b2d0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
b2e0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
b2f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b300: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
b310: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
b320: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
b330: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
b340: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
b350: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
b360: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b370: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
b380: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
b390: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
b3a0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
b3b0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
b3c0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
b3d0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
b3e0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
b3f0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
b400: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
b410: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
b420: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
b430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b440: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
b450: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
b460: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
b470: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
b480: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
b490: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
b4a0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
b4b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
b4c0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
b4d0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
b4e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b4f0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
b500: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
b510: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
b520: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
b530: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
b540: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
b550: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
b560: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
b570: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
b580: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
b590: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
b5a0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
b5b0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
b5c0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
b5d0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
b5e0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
b5f0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
b600: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
b610: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
b620: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
b630: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
b640: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
b650: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
b660: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
b670: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b680: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
b690: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
b6a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b6b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b6c0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
b6d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
b6e0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
b6f0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b700: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b710: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b720: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b730: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b740: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b750: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b760: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b770: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b780: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b790: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b7a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b7b0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b7c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b7d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b7e0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b7f0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b800: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b810: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b820: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b830: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b840: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b850: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b860: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b870: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b880: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b890: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b8a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b8b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b8c0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b8d0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b8e0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b8f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b900: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b910: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b920: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b930: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b940: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b950: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b960: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b970: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
b980: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
b990: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
b9a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b9b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
b9c0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
b9d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b9e0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
b9f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ba00: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
ba10: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ba20: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ba30: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
ba40: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
ba50: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
ba60: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
ba70: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
ba80: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
ba90: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
baa0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
bab0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
bac0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
bad0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
bae0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
baf0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
bb00: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
bb10: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
bb20: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
bb30: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
bb40: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
bb50: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
bb60: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
bb70: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
bb80: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
bb90: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
bba0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
bbb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
bbc0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
bbd0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
bbe0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
bbf0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
bc00: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
bc10: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
bc20: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
bc30: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
bc40: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
bc50: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
bc60: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
bc70: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
bc80: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
bc90: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
bca0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
bcb0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
bcc0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
bcd0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
bce0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
bcf0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
bd00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
bd10: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
bd20: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
bd30: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
bd40: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
bd50: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
bd60: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
bd70: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
bd80: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
bd90: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
bda0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
bdb0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
bdc0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
bdd0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
bde0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
bdf0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
be00: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
be10: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
be20: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
be30: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
be40: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
be50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
be60: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
be70: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
be80: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
be90: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
bea0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
beb0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
bec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
bed0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
bee0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
bef0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
bf00: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
bf10: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
bf20: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
bf30: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
bf40: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
bf50: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
bf60: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
bf70: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
bf80: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
bf90: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
bfa0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
bfb0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
bfc0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
bfd0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
bfe0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
bff0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
c000: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
c010: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
c020: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c030: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
c040: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
c050: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
c060: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
c070: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
c080: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
c090: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
c0a0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
c0b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
c0c0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
c0d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
c0e0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
c0f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
c100: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
c110: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
c120: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c130: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
c140: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
c150: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
c160: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
c170: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
c180: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
c190: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
c1a0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
c1b0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
c1c0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
c1d0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
c1e0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
c1f0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
c200: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
c210: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
c220: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
c230: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
c240: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
c250: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
c260: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
c270: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
c280: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
c290: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
c2a0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
c2b0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
c2c0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
c2d0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
c2e0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
c2f0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
c300: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
c310: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
c320: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
c330: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
c340: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
c350: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
c360: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
c370: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
c380: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
c390: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
c3a0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
c3b0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
c3c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
c3d0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
c3e0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
c3f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c400: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
c410: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
c420: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
c430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c440: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
c450: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
c460: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
c470: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
c480: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
c490: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
c4a0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
c4b0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
c4c0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
c4d0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c4e0: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
c4f0: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
c500: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
c510: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
c520: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
c530: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
c540: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
c550: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
c560: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
c570: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c580: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
c590: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
c5a0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
c5b0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
c5c0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
c5d0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
c5e0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
c5f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c600: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
c610: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c620: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
c630: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
c640: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
c650: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c660: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
c670: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
c680: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
c690: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
c6a0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
c6b0: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
c6c0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
c6d0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
c6e0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
c6f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
c700: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
c710: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
c720: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
c730: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c740: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
c750: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
c760: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
c770: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c780: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c790: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
c7a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
c7b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c7c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
c7d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
c7e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c7f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
c800: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
c810: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
c820: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
c830: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
c840: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
c850: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
c860: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
c870: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
c880: 72 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c  rface should onl
c890: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c8a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c8b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c8c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c8d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c8e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c8f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c900: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c910: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c920: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c930: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c940: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c950: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c960: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c970: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c980: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c990: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c9a0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c9b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c9c0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c9d0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c9e0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c9f0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
ca00: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
ca10: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
ca20: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
ca30: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
ca40: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
ca50: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
ca60: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
ca70: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
ca80: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
ca90: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
caa0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
cab0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
cac0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
cad0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
cae0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
caf0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
cb00: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
cb10: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
cb20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
cb30: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
cb40: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
cb50: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
cb60: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
cb70: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
cb80: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
cb90: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
cba0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cbb0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
cbc0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
cbd0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
cbe0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
cbf0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
cc00: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
cc10: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
cc20: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
cc30: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
cc40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
cc50: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
cc60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
cc70: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
cc80: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
cc90: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
cca0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
ccb0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
ccc0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
ccd0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
cce0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
ccf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
cd00: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
cd10: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
cd20: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
cd30: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
cd40: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
cd50: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
cd60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cd70: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
cd80: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
cd90: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
cda0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
cdb0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
cdc0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
cdd0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
cde0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
cdf0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
ce00: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
ce10: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
ce20: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
ce30: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
ce40: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
ce50: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
ce60: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
ce70: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
ce80: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
ce90: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
cea0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
ceb0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
cec0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
ced0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
cee0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
cef0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
cf00: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
cf10: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
cf20: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
cf30: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
cf40: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
cf50: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
cf60: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
cf70: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
cf80: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
cf90: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
cfa0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
cfb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
cfc0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
cfd0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
cfe0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
cff0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
d000: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
d010: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
d020: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
d030: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
d040: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
d050: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
d060: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
d070: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
d080: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
d090: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
d0a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
d0b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
d0c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
d0d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
d0e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
d0f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
d100: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
d110: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
d120: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
d130: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
d140: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
d150: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
d160: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
d170: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
d180: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
d190: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
d1a0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
d1b0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
d1c0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
d1d0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
d1e0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
d1f0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
d200: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
d210: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
d220: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
d230: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
d240: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
d250: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
d260: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
d270: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
d280: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
d290: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
d2a0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
d2b0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
d2c0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
d2d0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
d2e0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
d2f0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
d300: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
d310: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
d320: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
d330: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
d340: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d350: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
d360: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
d370: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
d380: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
d390: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
d3a0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
d3b0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
d3c0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
d3d0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
d3e0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
d3f0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
d400: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
d410: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
d420: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
d430: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
d440: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
d450: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
d460: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
d470: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
d480: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
d490: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
d4a0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
d4b0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
d4c0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
d4d0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
d4e0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
d4f0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
d500: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
d510: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
d520: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d530: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
d540: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
d550: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
d560: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
d570: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
d580: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
d590: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
d5a0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d5b0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
d5c0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d5d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d5e0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d5f0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d600: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d610: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d620: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d630: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d640: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d650: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d660: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
d670: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
d680: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
d690: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
d6a0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
d6b0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
d6c0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
d6d0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
d6e0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
d6f0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
d700: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d710: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
d720: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
d730: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
d740: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
d750: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
d760: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
d770: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
d780: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
d790: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d7a0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
d7b0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
d7c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
d7d0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
d7e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d7f0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
d800: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
d810: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
d820: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
d830: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
d840: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
d850: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
d860: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d870: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
d880: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
d890: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
d8a0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
d8b0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
d8c0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
d8d0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
d8e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
d8f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
d900: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
d910: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
d920: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
d930: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
d940: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
d950: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d960: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d970: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
d980: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
d990: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d9a0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
d9b0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
d9c0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
d9d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d9e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
d9f0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
da00: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
da10: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
da20: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
da30: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
da40: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
da50: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
da60: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
da70: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
da80: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
da90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
daa0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
dab0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
dac0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
dad0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
dae0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
daf0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
db00: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
db10: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
db20: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
db30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
db40: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
db50: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
db60: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
db70: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
db80: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
db90: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
dba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
dbb0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
dbc0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
dbd0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
dbe0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
dbf0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
dc00: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
dc10: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
dc20: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
dc30: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
dc40: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
dc50: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
dc60: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
dc70: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
dc80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
dc90: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
dca0: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
dcb0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
dcc0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
dcd0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
dce0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
dcf0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
dd00: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
dd10: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
dd20: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
dd30: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
dd40: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
dd50: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
dd60: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
dd70: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
dd80: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
dd90: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
dda0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
ddb0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
ddc0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
ddd0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
dde0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
ddf0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
de00: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
de10: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
de20: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
de30: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
de40: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
de50: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
de60: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
de70: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
de80: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
de90: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
dea0: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
deb0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
dec0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
ded0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
dee0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
def0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
df00: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
df10: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
df20: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
df30: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
df40: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
df50: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
df60: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
df70: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
df80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
df90: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
dfa0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
dfb0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
dfc0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
dfd0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
dfe0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
dff0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
e000: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e010: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
e020: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
e030: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
e040: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e050: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
e060: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e070: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
e080: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e090: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
e0a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
e0b0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
e0c0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
e0d0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
e0e0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
e0f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
e100: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
e110: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e120: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
e130: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
e140: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e150: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
e160: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
e170: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
e180: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
e190: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
e1a0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
e1b0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
e1c0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
e1d0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
e1e0: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
e1f0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
e200: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
e210: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
e220: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
e230: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
e240: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
e250: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
e260: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
e270: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
e280: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e290: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
e2a0: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
e2b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e2c0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e2d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
e2e0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
e2f0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
e300: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
e310: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
e320: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
e330: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
e340: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
e350: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
e360: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
e370: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
e380: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
e390: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
e3a0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
e3b0: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
e3c0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
e3d0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e3e0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e3f0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e400: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e410: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e420: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e430: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e440: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e450: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
e460: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
e470: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
e480: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
e490: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
e4a0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
e4b0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
e4c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
e4d0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
e4e0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
e4f0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
e500: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
e510: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
e520: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e530: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
e540: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
e550: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
e560: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
e570: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
e580: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
e590: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
e5a0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e5b0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
e5c0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
e5d0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
e5e0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
e5f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
e600: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
e610: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
e620: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
e630: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
e640: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
e650: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e660: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e670: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e680: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
e690: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
e6a0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
e6b0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
e6c0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
e6d0: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
e6e0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
e6f0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
e700: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
e710: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e720: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e730: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
e740: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e750: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
e760: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e770: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e780: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
e790: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e7a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e7b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e7c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e7d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e7e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e7f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e800: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
e810: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
e820: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
e830: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
e840: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e850: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e860: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
e870: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
e880: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e890: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
e8a0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
e8b0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
e8c0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
e8d0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
e8e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
e8f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e900: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
e910: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e920: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
e930: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e940: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
e950: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
e960: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e970: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e980: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e990: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e9a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e9b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e9c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e9d0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
e9e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e9f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
ea00: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
ea10: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
ea20: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
ea30: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
ea40: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
ea50: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
ea60: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
ea70: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
ea80: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
ea90: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
eaa0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
eab0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
eac0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
ead0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
eae0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
eaf0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
eb00: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
eb10: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
eb20: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
eb30: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
eb40: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
eb50: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
eb60: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
eb70: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
eb80: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
eb90: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
eba0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
ebb0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
ebc0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
ebd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ebe0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
ebf0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
ec00: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
ec10: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
ec20: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
ec30: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
ec40: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
ec50: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
ec60: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
ec70: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
ec80: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
ec90: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
eca0: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
ecb0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
ecc0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
ecd0: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
ece0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ecf0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
ed00: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
ed10: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
ed20: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
ed30: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
ed40: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
ed50: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
ed60: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
ed70: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
ed80: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
ed90: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
eda0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
edb0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
edc0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
edd0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
ede0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
edf0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
ee00: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
ee10: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
ee20: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
ee30: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
ee40: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
ee50: 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
ee60: 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
ee70: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
ee80: 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f  scrach allocatio
ee90: 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
eea0: 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
eeb0: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
eec0: 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
eed0: 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
eee0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
eef0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
ef00: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
ef10: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
ef20: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
ef30: 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
ef40: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
ef50: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
ef60: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
ef70: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
ef80: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
ef90: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
efa0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
efb0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
efc0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
efd0: 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
efe0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
eff0: 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
f000: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
f010: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
f020: 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
f030: 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
f040: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
f050: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
f060: 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
f070: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
f080: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
f090: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
f0a0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
f0b0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
f0c0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
f0d0: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
f0e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f0f0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
f100: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
f110: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
f120: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
f130: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
f140: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f150: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
f160: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
f170: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
f180: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
f190: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
f1a0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
f1b0: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
f1c0: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
f1d0: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
f1e0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
f1f0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
f200: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
f210: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
f220: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
f230: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
f240: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
f250: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
f260: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
f270: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
f280: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
f290: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
f2a0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
f2b0: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
f2c0: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
f2d0: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
f2e0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
f2f0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
f300: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
f310: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
f320: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
f330: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
f340: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
f350: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
f360: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
f370: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
f380: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
f390: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
f3a0: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
f3b0: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
f3c0: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
f3d0: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
f3e0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
f3f0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
f400: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
f410: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
f420: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
f430: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
f440: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
f450: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
f460: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
f470: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
f480: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
f490: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
f4a0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
f4b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
f4c0: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
f4d0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
f4e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f4f0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
f500: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
f510: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
f520: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
f530: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
f540: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
f550: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
f560: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
f570: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
f580: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
f590: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
f5a0: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
f5b0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
f5c0: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
f5d0: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
f5e0: 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
f5f0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f600: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
f610: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f620: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
f630: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
f640: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
f650: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
f660: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f670: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f680: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
f690: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
f6a0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
f6b0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
f6c0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
f6d0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
f6e0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
f6f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f700: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
f710: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
f720: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
f730: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
f740: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
f750: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
f760: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
f770: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
f780: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
f790: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
f7a0: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
f7b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
f7c0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
f7d0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
f7e0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
f7f0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
f800: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
f810: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
f820: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
f830: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
f840: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
f850: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
f860: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
f870: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
f880: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
f890: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
f8a0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
f8b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f8c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
f8d0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
f8e0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
f8f0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
f900: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
f910: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
f920: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
f930: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
f940: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
f950: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
f960: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
f970: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
f980: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
f990: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
f9a0: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
f9b0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
f9c0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
f9d0: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
f9e0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
f9f0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
fa00: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
fa10: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
fa20: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
fa30: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
fa40: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
fa50: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
fa60: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
fa70: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
fa80: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
fa90: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
faa0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
fab0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
fac0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
fad0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
fae0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
faf0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
fb00: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
fb10: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
fb20: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
fb30: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
fb40: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
fb50: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
fb60: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
fb70: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
fb80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
fb90: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
fba0: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
fbb0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
fbc0: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
fbd0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
fbe0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
fbf0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
fc00: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
fc10: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
fc20: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
fc30: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
fc40: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
fc50: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
fc60: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
fc70: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
fc80: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
fc90: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
fca0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
fcb0: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
fcc0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
fcd0: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
fce0: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
fcf0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fd00: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
fd10: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
fd20: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
fd30: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
fd40: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
fd50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
fd60: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
fd70: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
fd80: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
fd90: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
fda0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
fdb0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
fdc0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
fdd0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
fde0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
fdf0: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
fe00: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
fe10: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
fe20: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
fe30: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
fe40: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
fe50: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
fe60: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
fe70: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
fe80: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
fe90: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
fea0: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
feb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fec0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
fed0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
fee0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
fef0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ff00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ff10: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
ff20: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
ff30: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
ff40: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
ff50: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
ff60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ff70: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
ff80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
ff90: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
ffa0: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
ffb0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ffc0: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
ffd0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ffe0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
fff0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10000 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10010 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
10020 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10030 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
10040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
10050 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
10060 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10070 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
10080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10090 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
100a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
100b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
100c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
100d0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
100e0 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
100f0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
10100 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
10110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10120 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
10130 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
10140 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
10150 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
10160 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
10170 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
10180 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
10190 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
101a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
101b0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
101c0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
101d0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
101e0 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
101f0 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
10200 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10210 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
10220 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10230 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10240 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10250 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10260 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
10270 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
10280 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
10290 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
102a0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
102b0 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
102c0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
102d0 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
102e0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
102f0 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
10300 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
10310 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
10320 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
10330 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
10350 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
10360 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10370 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10380 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10390 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
103a0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
103b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
103c0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
103d0 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
103e0 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
103f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
10400 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
10410 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
10420 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10430 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
10440 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
10450 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
10460 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
10470 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
10480 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
10490 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
104a0 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
104b0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
104c0 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
104d0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
104e0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
104f0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
10500 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
10510 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
10520 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10530 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
10540 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
10550 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
10560 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
10570 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
10580 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
10590 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
105a0 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
105b0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
105c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
105d0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
105e0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
105f0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
10600 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
10610 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
10620 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
10630 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
10640 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
10650 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
10660 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
10670 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
10680 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
10690 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
106a0 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
106b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
106c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
106d0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
106e0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
106f0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
10700 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
10710 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
10720 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
10730 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
10740 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
10750 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
10760 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
10770 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
10780 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
10790 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
107a0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
107b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
107c0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
107d0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
107e0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
107f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
10800 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
10810 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
10820 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
10830 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
10840 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
10850 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
10860 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
10870 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
10880 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
10890 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
108a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
108b0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
108c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
108d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
108e0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
108f0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
10900 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10910 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
10920 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
10930 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10940 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
10950 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
10960 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10970 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10980 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
10990 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
109a0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
109b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
109c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
109d0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
109e0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
109f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10a00 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
10a10 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
10a20 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
10a30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10a40 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
10a50 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
10a60 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
10a70 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
10a80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10a90 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
10aa0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
10ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10ac0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
10ad0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
10ae0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
10af0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10b00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10b10 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
10b20 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10b30 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
10b40 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
10b50 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
10b60 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
10b70 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
10b80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10b90 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
10ba0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
10bb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10bc0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
10bd0 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
10be0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
10bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10c00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
10c10 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
10c20 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10c30 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10c40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10c50 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
10c60 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
10c70 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10c80 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
10c90 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
10ca0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
10cb0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
10cc0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
10cd0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
10ce0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10cf0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
10d00 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
10d10 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10d20 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
10d30 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
10d40 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
10d50 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10d60 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10d70 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10d80 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10d90 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
10da0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10db0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
10dc0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
10dd0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
10de0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
10df0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
10e00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10e10 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
10e20 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
10e30 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
10e40 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
10e50 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10e60 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10e70 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10e80 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10e90 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10ea0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10eb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
10ec0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
10ed0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
10ee0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10ef0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
10f00 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10f10 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
10f20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
10f30 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
10f40 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
10f50 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
10f60 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
10f70 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
10f80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10f90 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
10fa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
10fb0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10fc0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
10fd0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
10fe0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
10ff0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
11000 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
11010 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
11020 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
11030 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
11040 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11050 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
11060 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
11070 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
11080 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
11090 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
110a0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
110b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
110c0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
110d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
110e0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
110f0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
11100 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
11110 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
11120 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
11130 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
11140 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
11150 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
11160 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
11170 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
11180 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
11190 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
111a0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
111b0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
111c0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
111d0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
111e0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
111f0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
11200 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
11210 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11220 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
11230 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
11240 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
11250 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
11260 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
11270 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
11280 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
11290 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
112a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
112b0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
112c0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
112d0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
112e0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
112f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
11300 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
11310 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
11320 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
11330 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
11340 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
11350 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
11360 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
11370 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
11380 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
11390 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
113a0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
113b0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
113c0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
113d0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
113e0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
113f0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
11400 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11410 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
11420 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
11430 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
11440 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
11450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
11460 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11470 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
11480 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
11490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
114a0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
114b0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
114c0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
114d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
114e0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
114f0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
11500 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
11510 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
11520 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
11530 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
11540 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
11550 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
11560 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
11570 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
11580 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
11590 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
115a0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
115b0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
115c0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
115d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
115e0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
115f0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
11600 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
11610 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
11620 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
11630 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
11640 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
11650 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
11660 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
11670 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
11680 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
11690 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
116a0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
116b0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
116c0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
116d0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
116e0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
116f0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
11700 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
11710 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
11720 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
11730 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
11740 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
11750 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
11760 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
11770 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
11780 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11790 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
117a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
117b0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
117c0 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
117d0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
117e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
117f0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
11800 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
11810 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
11820 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
11830 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
11840 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
11850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
11860 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
11870 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
11880 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
11890 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
118a0 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
118b0 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
118c0 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
118d0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
118e0 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
118f0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
11900 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
11910 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
11920 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
11930 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11940 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
11950 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
11960 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
11970 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
11980 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
11990 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
119a0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
119b0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
119c0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
119d0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
119e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
119f0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
11a00 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
11a10 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
11a20 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
11a30 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
11a40 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
11a50 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
11a60 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
11a70 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
11a80 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
11a90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
11aa0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
11ab0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
11ac0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
11ad0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
11ae0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
11af0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
11b00 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
11b10 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
11b20 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
11b30 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
11b40 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
11b50 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
11b60 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
11b70 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
11b80 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
11b90 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
11ba0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
11bb0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
11bc0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
11bd0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
11be0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
11bf0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
11c00 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
11c10 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
11c20 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
11c30 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
11c40 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
11c50 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
11c60 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
11c70 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
11c80 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
11c90 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
11ca0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
11cb0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
11cc0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
11cd0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
11ce0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
11cf0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
11d00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
11d10 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
11d20 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
11d30 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
11d40 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
11d50 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
11d60 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
11d70 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
11d80 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11d90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
11da0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11db0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
11dc0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
11dd0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
11de0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
11df0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
11e00 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
11e10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
11e20 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
11e30 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
11e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11e50 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
11e60 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
11e70 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
11e80 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11e90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
11ea0 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
11eb0 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
11ec0 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
11ed0 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
11ee0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
11ef0 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
11f00 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
11f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f20 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
11f30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
11f40 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
11f50 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
11f60 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
11f70 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
11f80 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
11f90 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
11fa0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
11fb0 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
11fc0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
11fd0 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
11fe0 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
11ff0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
12000 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
12010 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
12020 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
12030 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
12040 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
12050 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
12060 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
12070 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
12080 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
12090 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
120a0 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
120b0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
120c0 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
120d0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
120e0 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
120f0 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
12100 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
12110 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
12120 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
12130 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
12140 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
12150 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
12160 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
12170 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
12180 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
12190 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
121a0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
121b0 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
121c0 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
121d0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
121e0 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
121f0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
12200 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
12210 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
12220 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
12230 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
12240 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
12250 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
12260 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
12270 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
12280 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
12290 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
122a0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
122b0 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
122c0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
122d0 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
122e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
122f0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
12300 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
12310 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
12320 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
12330 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
12340 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
12350 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
12360 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
12370 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
12380 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
12390 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
123a0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
123b0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
123c0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
123d0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
123e0 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
123f0 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
12400 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
12410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
12420 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
12430 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
12440 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
12450 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
12460 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
12470 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
12480 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
12490 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
124a0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
124b0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
124c0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
124d0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
124e0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
124f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
12500 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
12510 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
12520 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
12530 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
12540 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
12550 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
12560 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
12570 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
12580 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
12590 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
125a0 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
125b0 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
125c0 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
125d0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
125e0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
125f0 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
12600 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
12610 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
12620 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
12630 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
12640 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
12650 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
12660 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
12670 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
12680 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
12690 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
126a0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
126b0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
126c0 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
126d0 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
126e0 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
126f0 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
12700 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
12710 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12720 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
12730 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
12740 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
12750 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
12760 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
12770 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
12780 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
12790 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
127a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
127b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
127c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
127d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
127e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
127f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
12800 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
12810 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
12820 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12830 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
12840 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12850 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
12860 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
12870 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
12880 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
12890 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
128a0 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
128b0 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
128c0 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
128d0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
128e0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
128f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12900 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
12910 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
12920 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
12930 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
12940 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
12950 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
12960 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
12970 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
12980 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
12990 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
129a0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
129b0 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
129c0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
129d0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
129e0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
129f0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
12a00 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
12a10 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
12a20 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
12a30 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
12a40 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
12a50 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
12a60 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
12a70 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
12a80 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
12a90 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
12aa0 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
12ab0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
12ac0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
12ad0 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
12ae0 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
12af0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
12b00 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
12b10 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
12b20 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
12b30 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
12b40 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
12b50 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
12b60 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
12b70 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
12b80 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
12b90 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
12ba0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
12bb0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
12bc0 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
12bd0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
12be0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
12bf0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12c00 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12c10 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12c20 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
12c30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
12c40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
12c50 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
12c60 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
12c70 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
12c80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
12c90 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
12ca0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
12cb0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
12cc0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
12cd0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
12ce0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
12cf0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
12d00 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
12d10 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
12d20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12d30 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
12d40 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
12d50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12d60 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
12d70 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
12d80 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
12d90 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
12da0 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
12db0 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
12dc0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
12dd0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
12de0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
12df0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
12e00 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
12e10 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
12e20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
12e30 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
12e40 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
12e50 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
12e60 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
12e70 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
12e80 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
12e90 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
12ea0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
12eb0 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
12ec0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
12ed0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
12ee0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
12ef0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
12f00 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12f10 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
12f20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12f30 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
12f40 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
12f50 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
12f60 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12f70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
12f80 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
12f90 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
12fa0 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
12fb0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
12fc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
12fd0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
12fe0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
12ff0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
13000 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
13010 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
13020 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
13030 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
13040 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
13050 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
13060 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
13070 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13080 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
13090 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
130a0 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
130b0 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
130c0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
130d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
130e0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
130f0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
13100 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
13110 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
13120 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
13130 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
13140 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
13150 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
13160 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
13170 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
13180 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
13190 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
131a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
131b0 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
131c0 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
131d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
131e0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
131f0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
13200 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
13210 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
13220 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
13230 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
13240 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
13250 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
13260 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
13270 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
13280 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
13290 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
132a0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
132b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
132c0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
132d0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
132e0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
132f0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
13300 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
13310 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
13320 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
13330 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
13340 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
13350 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
13360 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
13370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
13380 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
13390 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
133a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
133b0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
133c0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
133d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
133e0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
133f0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
13400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
13410 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
13420 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
13430 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
13440 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
13450 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
13460 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
13470 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
13480 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
13490 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
134a0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
134b0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
134c0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
134d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
134e0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
134f0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
13500 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
13510 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
13520 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
13530 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
13540 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
13550 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
13560 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
13570 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
13580 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
13590 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
135a0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
135b0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
135c0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
135d0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
135e0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
135f0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
13600 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
13610 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
13620 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
13630 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
13640 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
13650 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
13660 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
13670 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
13680 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
13690 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
136a0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
136b0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
136c0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
136d0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
136e0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
136f0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
13700 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
13710 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
13720 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
13730 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
13740 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
13750 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
13760 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
13770 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
13780 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
13790 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
137a0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
137b0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
137c0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
137d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
137e0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
137f0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
13800 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
13810 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13820 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
13830 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
13840 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
13850 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
13860 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
13870 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
13880 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
13890 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
138a0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
138b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
138c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
138d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
138e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
138f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
13900 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
13910 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13920 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
13930 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
13940 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
13950 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
13960 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13970 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
13980 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
13990 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
139a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
139b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
139c0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
139d0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
139e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
139f0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
13a00 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
13a10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
13a20 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
13a30 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
13a40 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
13a50 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
13a60 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
13a70 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
13a80 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
13a90 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
13aa0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
13ab0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
13ac0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
13ad0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13ae0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
13af0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
13b00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13b10 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
13b20 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
13b30 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
13b40 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
13b50 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
13b60 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
13b70 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13b80 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
13b90 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
13ba0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
13bb0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
13bc0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13bd0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
13be0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
13bf0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
13c00 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
13c10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
13c20 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
13c30 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
13c40 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
13c50 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13c60 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
13c70 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
13c80 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
13c90 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
13ca0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
13cb0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
13cc0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
13cd0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
13ce0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
13cf0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
13d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13d10 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
13d20 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
13d30 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
13d40 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
13d50 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
13d60 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
13d70 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
13d80 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
13d90 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
13da0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
13db0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
13dc0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
13dd0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13de0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
13df0 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
13e00 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
13e10 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
13e20 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
13e30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
13e40 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
13e50 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
13e60 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
13e70 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
13e80 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
13e90 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
13ea0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
13eb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
13ec0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
13ed0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
13ee0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
13ef0 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
13f00 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
13f10 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
13f20 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
13f30 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
13f40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
13f50 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
13f60 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
13f70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
13f80 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
13f90 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
13fa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
13fb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
13fc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
13fd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
13fe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
13ff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
14000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
14010 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
14020 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
14030 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
14040 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
14050 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
14060 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
14070 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
14080 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
14090 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
140a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
140b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
140c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
140d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
140e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
140f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
14100 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
14110 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
14120 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
14130 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
14140 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
14150 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
14160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
14170 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
14180 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
14190 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
141a0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
141b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
141c0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
141d0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
141e0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
141f0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
14200 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
14210 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
14220 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
14230 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
14240 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
14250 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
14260 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
14270 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
14280 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
14290 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
142a0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
142b0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
142c0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
142d0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
142e0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
142f0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
14300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
14310 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
14320 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
14330 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
14340 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
14350 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
14360 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
14370 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
14380 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
14390 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
143a0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
143b0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
143c0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
143d0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
143e0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
143f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
14400 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
14410 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
14420 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
14430 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
14440 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
14450 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
14460 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
14470 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
14480 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
14490 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
144a0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
144b0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
144c0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
144d0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
144e0 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
144f0 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
14500 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
14510 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
14520 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
14530 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
14540 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
14550 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
14560 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
14570 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
14580 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
14590 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
145a0 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
145b0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
145c0 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
145d0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
145e0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
145f0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
14600 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
14610 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
14620 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
14630 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
14640 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
14650 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
14660 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
14670 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
14680 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
14690 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
146a0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
146b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
146c0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
146d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
146e0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
146f0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
14700 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
14710 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
14720 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14730 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
14740 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
14750 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
14760 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
14770 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
14780 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
14790 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
147a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
147b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
147c0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
147d0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
147e0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
147f0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
14800 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
14810 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
14820 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
14830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14840 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
14850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14860 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
14870 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14880 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
14890 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
148a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
148b0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
148c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
148d0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
148e0 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
148f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
14900 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
14910 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
14920 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
14930 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
14940 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
14950 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
14960 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
14970 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
14980 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
14990 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
149a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
149b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
149c0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
149d0 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
149e0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
149f0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
14a00 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
14a10 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
14a20 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
14a30 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
14a40 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
14a50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
14a60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14a70 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
14a80 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
14a90 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
14aa0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
14ab0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
14ac0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
14ad0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
14ae0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
14af0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
14b00 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
14b10 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
14b20 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
14b30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
14b40 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
14b50 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
14b60 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
14b70 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
14b80 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
14b90 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
14ba0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
14bb0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
14bc0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
14bd0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
14be0 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
14bf0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
14c00 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
14c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14c20 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
14c30 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
14c40 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
14c50 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
14c60 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
14c70 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
14c80 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14c90 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
14ca0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
14cb0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
14cc0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
14cd0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
14ce0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
14cf0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
14d00 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
14d10 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
14d20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14d30 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
14d40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
14d50 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
14d60 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
14d70 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
14d80 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
14d90 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
14da0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
14db0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
14dc0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
14dd0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
14de0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
14df0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
14e00 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
14e10 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
14e20 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
14e30 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
14e40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14e50 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
14e60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
14e70 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
14e80 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
14e90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
14ea0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
14eb0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
14ec0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
14ed0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
14ee0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
14ef0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
14f00 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
14f10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14f20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14f30 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14f40 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14f50 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14f60 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14f70 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14f80 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14f90 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
14fa0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
14fb0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
14fc0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
14fd0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
14fe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
14ff0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
15000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
15010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
15020 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
15030 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
15040 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
15050 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
15060 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
15070 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
15080 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
15090 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
150a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
150b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
150c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
150d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
150e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
150f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
15100 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
15110 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
15120 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
15130 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
15140 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
15150 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
15160 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15170 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
15180 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
15190 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
151a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
151b0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
151c0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
151d0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
151e0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
151f0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
15200 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
15210 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
15220 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
15230 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
15240 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
15250 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
15260 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
15270 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
15280 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
15290 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
152a0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
152b0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
152c0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
152d0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
152e0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
152f0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
15300 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
15310 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
15320 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
15330 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
15340 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15350 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
15360 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15370 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
15380 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15390 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
153a0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
153b0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
153c0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
153d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
153e0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
153f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15400 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
15410 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
15420 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
15430 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
15440 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
15450 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
15460 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
15470 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
15480 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
15490 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
154a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
154b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
154c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
154d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
154e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
154f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
15500 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
15510 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
15520 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
15530 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
15540 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
15550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
15560 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
15570 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
15580 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
15590 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
155a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
155b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
155c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
155d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
155e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
155f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
15600 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
15610 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
15620 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
15630 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
15640 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
15650 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
15660 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
15670 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
15680 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
15690 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
156a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
156b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
156c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
156d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
156e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
156f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
15700 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
15710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
15720 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
15730 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
15740 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
15750 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
15760 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
15770 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
15780 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
15790 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
157a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
157b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
157c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
157d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
157e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
157f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
15800 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
15810 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
15820 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
15830 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
15840 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
15850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
15860 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
15870 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15880 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15890 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
158a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
158b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
158c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
158d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
158e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
158f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15900 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15910 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15920 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
15930 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
15940 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
15950 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
15960 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
15970 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
15980 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15990 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
159a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
159b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
159c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
159d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
159e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
159f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15a00 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15a10 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15a20 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
15a30 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
15a40 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
15a50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
15a60 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
15a70 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
15a80 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
15a90 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
15aa0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
15ab0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
15ac0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15ad0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
15ae0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
15af0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
15b00 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
15b10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
15b20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15b30 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
15b40 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
15b50 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
15b60 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
15b70 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
15b80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
15b90 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
15ba0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
15bb0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
15bc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
15bd0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
15be0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
15bf0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
15c00 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
15c10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
15c20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15c30 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
15c40 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
15c50 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
15c60 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
15c70 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
15c80 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
15c90 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
15ca0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
15cb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15cc0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
15cd0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
15ce0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
15cf0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
15d00 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
15d10 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
15d20 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
15d30 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
15d40 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
15d50 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
15d60 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
15d70 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
15d80 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
15d90 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15da0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
15db0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
15dc0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
15dd0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15de0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
15df0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
15e00 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
15e10 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
15e20 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
15e30 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
15e40 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
15e50 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
15e60 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
15e70 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
15e80 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
15e90 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
15ea0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
15eb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
15ec0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15ed0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
15ee0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
15ef0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
15f00 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
15f10 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
15f20 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
15f30 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15f40 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
15f50 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
15f60 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
15f70 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
15f80 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
15f90 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
15fa0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
15fb0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
15fc0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
15fd0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
15fe0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
15ff0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
16000 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
16010 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
16020 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
16030 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
16040 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
16050 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
16060 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
16070 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
16080 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
16090 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
160a0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
160b0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
160c0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
160d0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
160e0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
160f0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
16100 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
16110 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
16120 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
16130 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
16140 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
16150 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
16160 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
16170 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
16180 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
16190 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
161a0 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
161b0 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
161c0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
161d0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
161e0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
161f0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
16200 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
16210 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
16220 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
16230 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
16240 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
16250 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
16260 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
16270 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
16280 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
16290 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
162a0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
162b0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
162c0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
162d0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
162e0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
162f0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
16300 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
16310 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
16320 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
16330 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
16340 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
16350 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16360 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
16370 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
16380 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
16390 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
163a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
163b0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
163c0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
163d0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
163e0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
163f0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
16400 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
16410 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
16420 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
16430 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
16440 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16450 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
16460 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
16470 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
16480 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
16490 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
164a0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
164b0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
164c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
164d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
164e0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
164f0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
16500 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
16510 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
16520 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16530 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
16540 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
16550 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
16560 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
16570 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
16580 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
16590 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
165a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
165b0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
165c0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
165d0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
165e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
165f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
16600 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
16610 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
16620 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
16630 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
16640 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
16650 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
16660 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
16670 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
16680 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
16690 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
166a0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
166b0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
166c0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
166d0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
166e0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
166f0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
16700 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
16710 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
16720 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
16730 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
16740 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
16750 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
16760 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
16770 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
16780 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
16790 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
167a0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
167b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
167c0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
167d0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
167e0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
167f0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
16800 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
16810 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
16820 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
16830 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
16840 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
16850 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16860 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
16870 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
16880 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
16890 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
168a0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
168b0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
168c0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
168d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
168e0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
168f0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
16900 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
16910 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
16920 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
16930 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
16940 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
16950 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
16960 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
16970 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
16980 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
16990 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
169a0 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
169b0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
169c0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
169d0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
169e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
169f0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
16a00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
16a10 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
16a20 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
16a30 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
16a40 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
16a50 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
16a60 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
16a70 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
16a80 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
16a90 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
16aa0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
16ab0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
16ac0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
16ad0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
16ae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16af0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
16b00 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
16b10 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
16b20 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
16b30 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
16b40 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
16b50 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
16b60 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
16b70 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
16b80 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
16b90 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
16ba0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
16bb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16bc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
16bd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16be0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
16bf0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
16c00 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
16c10 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
16c20 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
16c30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16c40 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
16c50 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
16c60 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
16c70 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
16c80 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
16c90 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
16ca0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
16cb0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
16cc0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
16cd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16ce0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
16cf0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
16d00 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
16d10 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
16d20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
16d30 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
16d40 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
16d50 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
16d60 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
16d70 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
16d80 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
16d90 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
16da0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
16db0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
16dc0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
16dd0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
16de0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
16df0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
16e00 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
16e10 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
16e20 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
16e30 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
16e40 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
16e50 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
16e60 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
16e70 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
16e80 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
16e90 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
16ea0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
16eb0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
16ec0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
16ed0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
16ee0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
16ef0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
16f00 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
16f10 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
16f20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
16f30 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
16f40 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
16f50 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
16f60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
16f70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16f80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
16f90 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
16fa0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
16fb0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
16fc0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
16fd0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
16fe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
16ff0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
17000 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
17010 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
17020 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
17030 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17040 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
17050 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
17060 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
17070 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
17080 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17090 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
170a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
170b0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
170c0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
170d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
170e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
170f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
17100 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17110 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17120 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
17130 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17140 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
17150 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
17160 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
17170 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
17180 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
17190 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
171a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
171b0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
171c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
171d0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
171e0 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
171f0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
17200 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
17210 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
17220 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
17230 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
17240 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
17250 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
17260 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
17270 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
17280 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
17290 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
172a0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
172b0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
172c0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
172d0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
172e0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
172f0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
17300 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
17310 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
17320 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
17330 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
17340 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17350 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
17360 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
17370 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
17380 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
17390 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
173a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
173b0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
173c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
173d0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
173e0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
173f0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
17400 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
17410 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
17420 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
17430 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
17440 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
17450 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
17460 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
17470 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
17480 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
17490 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
174a0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
174b0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
174c0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
174d0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
174e0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
174f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
17500 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
17510 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
17520 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
17530 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
17540 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
17550 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
17560 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
17570 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
17580 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
17590 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
175a0 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
175b0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
175c0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
175d0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
175e0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
175f0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
17600 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
17610 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
17620 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
17630 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
17640 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
17650 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
17660 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
17670 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
17680 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
17690 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
176a0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
176b0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
176c0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
176d0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
176e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
176f0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
17700 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
17710 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
17720 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
17730 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
17740 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
17750 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
17760 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
17770 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
17780 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
17790 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
177a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
177b0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
177c0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
177d0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
177e0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
177f0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
17800 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
17810 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
17820 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
17830 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
17840 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
17850 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
17860 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
17870 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
17880 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
17890 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
178a0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
178b0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
178c0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
178d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
178e0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
178f0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
17900 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
17910 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
17920 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
17930 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
17940 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
17950 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17960 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
17970 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
17980 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
17990 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
179a0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
179b0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
179c0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
179d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
179e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
179f0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
17a00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17a10 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
17a20 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
17a30 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
17a40 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
17a50 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
17a60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
17a70 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
17a80 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
17a90 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
17aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17ab0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
17ac0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
17ad0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
17ae0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
17af0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
17b00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
17b10 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
17b20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
17b30 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
17b40 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
17b50 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
17b60 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
17b70 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
17b80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
17b90 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
17ba0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
17bb0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
17bc0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
17bd0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
17be0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17bf0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
17c00 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
17c10 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
17c20 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
17c30 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
17c40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
17c50 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
17c60 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
17c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
17c80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
17c90 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
17ca0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
17cb0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
17cc0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
17cd0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
17ce0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
17cf0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
17d00 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
17d10 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17d20 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
17d30 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
17d40 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
17d50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
17d60 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
17d70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
17d80 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
17d90 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
17da0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
17db0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
17dc0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
17dd0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
17de0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
17df0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
17e00 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
17e10 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
17e20 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
17e30 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
17e40 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
17e50 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
17e60 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
17e70 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
17e80 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
17e90 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
17ea0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
17eb0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
17ec0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
17ed0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
17ee0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
17ef0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
17f00 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
17f10 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
17f20 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
17f30 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
17f40 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
17f50 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
17f60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
17f70 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
17f80 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
17f90 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
17fa0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
17fb0 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
17fc0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
17fd0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
17fe0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
17ff0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
18000 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
18010 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
18020 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
18030 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
18040 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
18050 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
18060 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
18070 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
18080 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
18090 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
180a0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
180b0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
180c0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
180d0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
180e0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
180f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
18100 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
18110 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
18120 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
18130 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
18140 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  a authorizer cal
18150 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
18160 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
18170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18180 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
18190 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
181a0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
181b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
181c0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
181d0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
181e0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
181f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
18200 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
18210 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
18220 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
18230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18240 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
18250 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
18260 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
18270 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
18280 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
18290 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
182a0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
182b0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
182c0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
182d0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
182e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
182f0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
18300 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
18310 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
18320 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
18330 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
18340 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
18350 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
18360 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
18370 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
18380 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
18390 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
183a0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
183b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
183c0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
183d0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
183e0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
183f0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
18400 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
18410 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
18420 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
18430 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
18440 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
18450 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
18460 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
18470 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
18480 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
18490 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
184a0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
184b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
184c0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
184d0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
184e0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
184f0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
18500 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
18510 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
18520 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
18530 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
18540 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
18550 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
18560 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
18570 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
18580 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
18590 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
185a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
185b0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
185c0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
185d0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
185e0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
185f0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
18600 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
18610 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
18620 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
18630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
18640 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
18650 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18660 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
18670 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
18680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18690 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
186a0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
186b0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
186c0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
186d0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
186e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
186f0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
18700 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
18710 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
18720 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
18730 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
18740 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
18750 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
18760 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
18770 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
18780 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
18790 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
187a0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
187b0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
187c0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
187d0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
187e0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
187f0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
18800 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
18810 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18820 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
18830 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
18840 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
18850 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
18860 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
18870 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
18880 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
18890 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
188a0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
188b0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
188c0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
188d0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
188e0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
188f0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
18900 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
18910 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
18920 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
18930 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
18940 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
18950 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
18960 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
18970 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
18980 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
18990 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
189a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
189b0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
189c0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
189d0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
189e0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
189f0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
18a00 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
18a10 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
18a20 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
18a30 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
18a40 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
18a50 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
18a60 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
18a70 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
18a80 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
18a90 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
18aa0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
18ab0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
18ac0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
18ad0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
18ae0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
18af0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
18b00 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
18b10 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
18b20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
18b30 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
18b40 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
18b50 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
18b60 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
18b70 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
18b80 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
18b90 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
18ba0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
18bb0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
18bc0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
18bd0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
18be0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
18bf0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
18c00 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
18c10 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
18c20 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
18c30 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
18c40 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
18c50 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
18c60 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
18c70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
18c80 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
18c90 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
18ca0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
18cb0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
18cc0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
18cd0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
18ce0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
18cf0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
18d00 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
18d10 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
18d20 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
18d30 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
18d40 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
18d50 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
18d60 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
18d70 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
18d80 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
18d90 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
18da0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
18db0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
18dc0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
18dd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
18de0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
18df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18e00 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
18e10 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
18e20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18e30 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
18e40 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
18e50 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
18e60 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
18e70 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
18e80 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
18e90 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
18ea0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
18eb0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
18ec0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18ed0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
18ee0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
18ef0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
18f00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18f10 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
18f20 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
18f30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
18f40 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
18f50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18f60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18f70 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
18f80 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
18f90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18fa0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
18fb0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
18fc0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
18fd0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
18fe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18ff0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
19000 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
19010 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
19020 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
19030 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
19040 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19050 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
19060 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
19070 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
19080 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
19090 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
190a0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
190b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
190c0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
190d0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
190e0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
190f0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
19100 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19110 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
19120 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
19130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
19140 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
19150 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
19160 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
19170 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
19180 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
19190 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
191a0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
191b0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
191c0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
191d0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
191e0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
191f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19200 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
19210 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
19220 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
19230 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
19240 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
19250 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
19260 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
19270 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
19280 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
19290 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
192a0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
192b0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
192c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
192d0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
192e0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
192f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
19300 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
19310 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19320 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
19330 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
19340 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
19350 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
19360 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
19370 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
19380 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
19390 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
193a0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
193b0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
193c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
193d0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
193e0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
193f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
19400 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
19410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19420 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
19430 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
19440 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
19450 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
19460 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
19470 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
19480 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
19490 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
194a0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
194b0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
194c0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
194d0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
194e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
194f0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
19500 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
19510 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
19520 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
19530 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
19540 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
19550 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
19560 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
19570 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
19580 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
19590 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
195a0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
195b0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
195c0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
195d0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
195e0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
195f0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
19600 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
19610 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
19620 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
19630 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
19640 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
19650 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
19660 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
19670 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
19680 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
19690 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
196a0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
196b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
196c0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
196d0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
196e0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
196f0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
19700 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
19710 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
19720 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
19730 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
19740 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
19750 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
19760 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
19770 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
19780 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
19790 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
197a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
197b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
197c0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
197d0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
197e0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
197f0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
19800 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
19810 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
19820 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
19830 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
19840 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
19850 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
19860 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
19870 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19880 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19890 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
198a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
198b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
198c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
198d0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
198e0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
198f0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
19900 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19910 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19920 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
19930 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
19940 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19950 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19960 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19970 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
19980 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
19990 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
199a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
199b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
199c0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
199d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
199e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
199f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19a00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
19a10 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
19a20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
19a30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
19a40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19a50 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
19a60 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
19a70 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
19a80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19a90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19aa0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
19ab0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
19ac0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
19ad0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19ae0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19af0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
19b00 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
19b10 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
19b20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19b30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19b40 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
19b50 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
19b60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19b70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19b80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19b90 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
19ba0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
19bb0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
19bc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19bd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19be0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
19bf0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
19c00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
19c10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19c30 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
19c40 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
19c50 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
19c60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19c80 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
19c90 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
19ca0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19cb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19cd0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
19ce0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
19cf0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
19d00 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19d20 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
19d30 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
19d40 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
19d50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19d70 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19d80 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
19d90 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
19da0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19db0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19dc0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
19dd0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
19de0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
19df0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19e00 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
19e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
19e20 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
19e30 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19e40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19e50 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
19e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
19e70 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
19e80 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
19e90 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
19ea0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
19eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
19ec0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19ed0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
19ee0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19ef0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
19f00 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
19f10 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
19f20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19f30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19f40 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
19f50 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
19f60 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
19f70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19f80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19f90 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
19fa0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
19fb0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19fc0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
19fd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19fe0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
19ff0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1a000 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1a010 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a020 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a030 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1a040 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1a050 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1a060 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a070 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a080 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1a090 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1a0a0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1a0b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a0c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a0d0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1a0e0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1a0f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1a100 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a120 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1a130 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1a140 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1a150 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1a160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a170 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1a180 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1a190 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1a1a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1a1b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1a1c0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1a1d0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1a1e0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1a1f0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1a200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1a210 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1a220 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1a230 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1a240 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1a250 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1a260 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1a270 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1a280 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1a290 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1a2a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1a2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a2c0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1a2d0 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
1a2e0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1a2f0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1a300 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1a310 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1a320 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1a330 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
1a340 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
1a350 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
1a360 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
1a370 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
1a380 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1a390 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1a3a0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1a3b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
1a3c0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
1a3d0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
1a3e0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
1a3f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
1a400 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
1a410 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1a420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
1a430 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
1a440 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
1a450 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
1a460 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
1a470 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
1a480 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
1a490 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
1a4a0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
1a4b0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
1a4c0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
1a4d0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
1a4e0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1a4f0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1a500 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1a510 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1a520 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1a530 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1a540 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1a550 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
1a560 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
1a570 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1a580 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1a590 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1a5a0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1a5b0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1a5c0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
1a5d0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1a5e0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
1a5f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1a600 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
1a610 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
1a620 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
1a630 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
1a640 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
1a650 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
1a660 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1a670 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
1a680 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
1a690 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
1a6a0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
1a6b0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
1a6c0 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
1a6d0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
1a6e0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
1a6f0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
1a700 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
1a710 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
1a720 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
1a730 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1a740 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
1a750 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
1a760 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
1a770 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
1a780 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
1a790 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
1a7a0 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
1a7b0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
1a7c0 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
1a7d0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1a7e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1a7f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
1a800 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1a810 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1a820 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1a830 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1a840 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
1a850 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1a860 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1a870 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1a880 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1a890 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1a8a0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1a8b0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a8c0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1a8d0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1a8e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a8f0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a900 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1a910 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1a920 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1a930 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1a940 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1a950 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1a960 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1a970 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
1a980 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1a990 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
1a9a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a9b0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
1a9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1a9d0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1a9e0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1a9f0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1aa00 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1aa10 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1aa20 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
1aa30 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
1aa40 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
1aa50 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1aa60 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
1aa70 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1aa80 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
1aa90 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ter N is the num
1aaa0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1aab0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1aac0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1aad0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1aae0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1aaf0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1ab00 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1ab10 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
1ab20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
1ab30 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
1ab40 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
1ab50 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
1ab60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
1ab70 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
1ab80 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1ab90 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
1aba0 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
1abb0 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
1abc0 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
1abd0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1abe0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
1abf0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
1ac00 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
1ac10 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
1ac20 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
1ac30 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
1ac40 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1ac50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1ac60 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1ac70 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1ac80 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1ac90 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1aca0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1acb0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1acc0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1acd0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1ace0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1acf0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1ad00 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1ad10 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1ad20 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1ad30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ad40 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1ad50 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1ad60 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1ad70 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1ad80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ad90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1ada0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1adb0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1adc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1add0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1ade0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1adf0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1ae00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ae10 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1ae20 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1ae30 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1ae40 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1ae50 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1ae60 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1ae70 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
1ae80 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1ae90 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
1aea0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68  database file wh
1aeb0 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65  ose name is give
1aec0 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65  n by the.** file
1aed0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1aee0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1aef0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1af00 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1af10 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1af20 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1af30 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1af40 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1af50 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1af60 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1af70 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1af80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1af90 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1afa0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1afb0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1afc0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1afd0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1afe0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1aff0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1b000 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1b010 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1b020 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1b030 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1b040 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1b050 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1b060 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1b070 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1b080 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1b090 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1b0a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1b0b0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1b0c0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1b0d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1b0e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1b0f0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1b100 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1b110 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1b120 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1b130 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1b140 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1b150 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1b160 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1b170 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1b180 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1b190 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1b1a0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1b1b0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
1b1c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
1b1d0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
1b1e0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1b1f0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1b200 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1b210 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1b220 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1b230 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1b240 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1b250 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1b260 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1b270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1b280 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1b290 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1b2a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1b2b0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1b2c0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1b2d0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1b2e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1b2f0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1b300 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1b310 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1b320 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1b330 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1b340 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1b350 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1b360 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1b370 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1b380 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1b390 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1b3a0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1b3b0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1b3c0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1b3d0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1b3e0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1b3f0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1b400 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
1b410 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
1b420 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1b430 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
1b440 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1b450 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1b460 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1b470 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1b480 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1b490 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1b4a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1b4b0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1b4c0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1b4d0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ,.** and/or [SQL
1b4e0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1b4f0 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a  CACHE] flags:)^.
1b500 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1b510 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1b520 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1b530 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1b540 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1b550 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1b560 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1b570 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1b580 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1b590 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1b5a0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1b5b0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1b5c0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1b5d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1b5e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1b5f0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1b600 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1b610 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1b620 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1b630 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1b640 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1b650 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1b660 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1b670 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1b680 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1b690 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1b6a0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1b6b0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1b6c0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1b6d0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1b6e0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1b6f0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1b700 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1b710 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1b720 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1b730 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1b740 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1b750 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1b760 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1b770 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1b780 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1b790 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1b7a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1b7b0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1b7c0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1b7d0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1b7e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1b7f0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1b800 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1b810 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1b820 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
1b830 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
1b840 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
1b850 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
1b860 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1b870 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1b880 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1b890 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
1b8a0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
1b8b0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1b8c0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1b8d0 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20   flags,.** then 
1b8e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1b8f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1b900 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
1b910 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1b920 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
1b930 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b940 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
1b950 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
1b960 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
1b970 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
1b980 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
1b990 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
1b9a0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
1b9b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1b9c0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
1b9d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1b9e0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
1b9f0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
1ba00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ba10 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
1ba20 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
1ba30 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1ba40 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
1ba50 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
1ba60 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
1ba70 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
1ba80 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1ba90 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
1baa0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1bab0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1bac0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1bad0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
1bae0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
1baf0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
1bb00 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
1bb10 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1bb20 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
1bb30 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
1bb40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
1bb50 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1bb60 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
1bb70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1bb80 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
1bb90 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1bba0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1bbb0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
1bbc0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
1bbd0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
1bbe0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
1bbf0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1bc00 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
1bc10 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
1bc20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
1bc30 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
1bc40 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
1bc50 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1bc60 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
1bc70 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1bc80 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1bc90 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1bca0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1bcb0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1bcc0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1bcd0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1bce0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1bcf0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1bd00 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1bd10 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1bd20 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1bd30 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1bd40 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1bd50 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1bd60 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1bd70 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1bd80 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1bd90 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1bda0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1bdb0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1bdc0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1bdd0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1bde0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1bdf0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
1be00 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1be10 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
1be20 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
1be30 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1be40 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
1be50 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1be60 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1be70 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1be80 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1be90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bea0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1beb0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
1bec0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1bed0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1bee0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1bef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
1bf00 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
1bf10 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
1bf20 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1bf30 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
1bf40 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1bf50 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
1bf60 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
1bf70 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1bf80 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1bf90 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
1bfa0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1bfb0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
1bfc0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
1bfd0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
1bfe0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
1bff0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
1c000 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1c010 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
1c020 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1c030 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
1c040 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
1c050 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
1c060 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
1c070 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
1c080 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
1c090 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
1c0a0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
1c0b0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
1c0c0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
1c0d0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
1c0e0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
1c0f0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1c100 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69  _open_v2()..*/.i
1c110 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1c120 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1c130 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1c140 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1c150 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1c160 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1c170 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1c180 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1c190 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1c1a0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
1c1b0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
1c1c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1c1d0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
1c1e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1c1f0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1c200 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1c210 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1c220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c230 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1c240 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1c250 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1c260 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1c270 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
1c280 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1c290 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1c2a0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
1c2b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
1c2c0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
1c2d0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
1c2e0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
1c2f0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
1c300 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1c310 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
1c320 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
1c330 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c340 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
1c350 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1c360 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
1c370 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
1c380 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1c390 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
1c3a0 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
1c3b0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
1c3c0 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
1c3d0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1c3e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
1c3f0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
1c400 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
1c410 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1c420 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
1c430 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
1c440 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
1c450 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1c460 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
1c470 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
1c480 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
1c490 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
1c4a0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
1c4b0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
1c4c0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
1c4d0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1c4e0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
1c4f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1c500 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
1c510 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
1c520 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1c530 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
1c540 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
1c550 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
1c560 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
1c570 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1c580 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
1c590 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1c5a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
1c5b0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1c5c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
1c5d0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
1c5e0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
1c5f0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1c600 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1c610 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
1c620 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
1c630 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
1c640 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
1c650 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
1c660 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
1c670 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
1c680 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
1c690 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
1c6a0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
1c6b0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1c6c0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1c6d0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
1c6e0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
1c6f0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
1c700 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
1c710 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
1c720 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
1c730 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
1c740 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
1c750 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
1c760 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
1c770 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
1c780 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
1c790 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
1c7a0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
1c7b0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
1c7c0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
1c7d0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
1c7e0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
1c7f0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
1c800 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
1c810 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
1c820 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
1c830 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1c840 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
1c850 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1c860 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
1c870 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1c880 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
1c890 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
1c8a0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
1c8b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
1c8c0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
1c8d0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
1c8e0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
1c8f0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
1c900 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
1c910 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
1c920 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
1c930 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
1c940 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
1c950 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
1c960 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
1c970 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
1c980 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
1c990 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
1c9a0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
1c9b0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
1c9c0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
1c9d0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
1c9e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1c9f0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
1ca00 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
1ca10 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
1ca20 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1ca30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1ca40 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1ca50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1ca60 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1ca70 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1ca80 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1ca90 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
1caa0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
1cab0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
1cac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cad0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
1cae0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
1caf0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
1cb00 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
1cb10 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
1cb20 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
1cb30 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
1cb40 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
1cb50 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
1cb60 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
1cb70 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
1cb80 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
1cb90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
1cba0 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
1cbb0 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
1cbc0 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
1cbd0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1cbe0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
1cbf0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1cc00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cc10 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
1cc20 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
1cc30 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
1cc40 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
1cc50 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
1cc60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1cc70 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
1cc80 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
1cc90 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
1cca0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1ccb0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
1ccc0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1ccd0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
1cce0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1ccf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1cd00 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
1cd10 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
1cd20 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
1cd30 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1cd40 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
1cd50 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1cd60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1cd70 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
1cd80 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
1cd90 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
1cda0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
1cdb0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
1cdc0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1cdd0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
1cde0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1cdf0 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
1ce00 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1ce10 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
1ce20 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  its.**.** ^(This
1ce30 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1ce40 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
1ce50 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
1ce60 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
1ce70 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
1ce80 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
1ce90 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
1cea0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1ceb0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
1cec0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
1ced0 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
1cee0 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
1cef0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1cf00 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1cf10 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
1cf20 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
1cf30 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
1cf40 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
1cf50 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
1cf60 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
1cf70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1cf80 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
1cf90 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
1cfa0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
1cfb0 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
1cfc0 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
1cfd0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
1cfe0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
1cff0 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
1d000 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
1d010 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
1d020 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
1d030 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
1d040 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
1d050 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d060 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
1d070 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
1d080 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
1d090 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
1d0a0 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
1d0b0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1d0c0 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1d0d0 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
1d0e0 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
1d0f0 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1d100 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1d110 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1d120 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1d130 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1d140 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
1d150 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
1d160 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1d170 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
1d180 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
1d190 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
1d1a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1d1b0 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
1d1c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
1d1d0 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
1d1e0 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
1d1f0 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
1d200 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
1d210 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
1d220 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
1d230 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
1d240 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1d250 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
1d260 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
1d270 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1d280 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1d290 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1d2a0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1d2b0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1d2c0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
1d2d0 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
1d2e0 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
1d2f0 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
1d300 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
1d310 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
1d320 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
1d330 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
1d340 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
1d350 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
1d360 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
1d370 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
1d380 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
1d390 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
1d3a0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
1d3b0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
1d3c0 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
1d3d0 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
1d3e0 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
1d3f0 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
1d400 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
1d410 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
1d420 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
1d430 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
1d440 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
1d450 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
1d460 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
1d470 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
1d480 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
1d490 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
1d4a0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
1d4b0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
1d4c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d4d0 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
1d4e0 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
1d4f0 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
1d500 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
1d510 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1d520 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
1d530 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
1d540 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
1d550 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
1d560 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1d570 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
1d580 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
1d590 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
1d5a0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
1d5b0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
1d5c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
1d5d0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
1d5e0 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
1d5f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d600 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
1d610 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
1d620 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1d630 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
1d640 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
1d650 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
1d660 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
1d670 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
1d680 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
1d690 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
1d6a0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
1d6b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1d6c0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
1d6d0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
1d6e0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
1d6f0 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
1d700 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
1d710 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1d720 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
1d730 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
1d740 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
1d750 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1d760 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d770 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1d780 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d790 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1d7a0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1d7b0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
1d7c0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  s.<dd>)^.**.** ^
1d7d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d7e0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
1d7f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d800 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
1d810 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
1d820 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
1d830 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d840 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1d850 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1d860 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d870 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1d880 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1d890 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1d8a0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
1d8b0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
1d8c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d8d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
1d8e0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
1d8f0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
1d900 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
1d910 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1d920 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1d930 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1d940 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1d950 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1d960 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1d970 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1d980 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1d990 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1d9a0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
1d9b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d9c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
1d9d0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
1d9e0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
1d9f0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1da00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1da10 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
1da20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1da30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
1da40 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
1da50 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1da60 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
1da70 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
1da80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1da90 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
1daa0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
1dab0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
1dac0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
1dad0 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
1dae0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
1daf0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
1db00 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1db10 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1db20 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
1db30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1db40 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1db50 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
1db60 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1db70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1db80 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1db90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1dba0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
1dbb0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
1dbc0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
1dbd0 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  >.**.** ^(<dt>SQ
1dbe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1dbf0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
1dc00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1dc10 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1dc20 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
1dc30 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
1dc40 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
1dc50 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
1dc60 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1dc70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1dc80 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
1dc90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1dca0 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
1dcb0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
1dcc0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
1dcd0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
1dce0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1dcf0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1dd00 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1dd10 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1dd20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
1dd30 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
1dd40 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
1dd50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1dd60 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
1dd70 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
1dd80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1dd90 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
1dda0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
1ddb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ddc0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
1ddd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1dde0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ddf0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1de00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1de10 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
1de20 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1de30 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1de40 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1de50 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
1de60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1de70 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
1de80 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1de90 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
1dea0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
1deb0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1dec0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
1ded0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
1dee0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1def0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
1df00 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
1df10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1df20 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
1df30 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
1df40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1df50 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
1df60 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
1df70 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1df80 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
1df90 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
1dfa0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
1dfb0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
1dfc0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
1dfd0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
1dfe0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
1dff0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
1e000 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
1e010 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1e020 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
1e030 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1e040 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
1e050 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1e060 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
1e070 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
1e080 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1e090 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e0a0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1e0b0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
1e0c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1e0d0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
1e0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
1e0f0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
1e100 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
1e110 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1e120 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
1e130 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
1e140 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
1e150 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
1e160 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1e170 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
1e180 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
1e190 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e1a0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
1e1b0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
1e1c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e1d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1e1e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
1e1f0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
1e200 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
1e210 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
1e220 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
1e230 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
1e240 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
1e250 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1e260 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
1e270 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1e280 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
1e290 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
1e2a0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
1e2b0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
1e2c0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1e2d0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
1e2e0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
1e2f0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
1e300 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
1e310 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
1e320 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
1e330 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
1e340 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
1e350 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
1e360 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
1e370 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
1e380 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
1e390 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
1e3a0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1e3b0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1e3c0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
1e3d0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1e3e0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1e3f0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
1e400 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1e410 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
1e420 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
1e430 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
1e440 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1e450 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  bytes..**.** ^If
1e460 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
1e470 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
1e480 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1e490 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
1e4a0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
1e4b0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
1e4c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1e4d0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
1e4e0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
1e4f0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
1e500 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
1e510 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
1e520 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1e530 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
1e540 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
1e550 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
1e560 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1e570 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
1e580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e590 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
1e5a0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
1e5b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e5c0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
1e5d0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
1e5e0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
1e5f0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
1e600 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1e610 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1e620 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
1e630 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
1e640 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1e650 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1e660 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
1e670 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
1e680 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
1e690 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
1e6a0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
1e6b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
1e6c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1e6d0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
1e6e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1e6f0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
1e700 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
1e710 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
1e720 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
1e730 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
1e740 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
1e750 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
1e760 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
1e770 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1e780 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1e790 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1e7a0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
1e7b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e7c0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
1e7d0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
1e7e0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
1e7f0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
1e800 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
1e810 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
1e820 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
1e830 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
1e840 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
1e850 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
1e860 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
1e870 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
1e880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
1e890 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
1e8a0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
1e8b0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
1e8c0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
1e8d0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
1e8e0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
1e8f0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
1e900 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
1e910 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
1e920 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
1e930 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
1e940 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1e950 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
1e960 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
1e970 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
1e980 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
1e990 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
1e9a0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
1e9b0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
1e9c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
1e9d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1e9e0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
1e9f0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1ea00 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
1ea10 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
1ea20 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
1ea30 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1ea40 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1ea50 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
1ea60 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
1ea70 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
1ea80 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1ea90 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
1eaa0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
1eab0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
1eac0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ead0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
1eae0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
1eaf0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
1eb00 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
1eb10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1eb20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1eb30 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1eb40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1eb50 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
1eb60 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
1eb70 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1eb80 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1eb90 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1eba0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1ebb0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1ebc0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1ebd0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1ebe0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1ebf0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1ec00 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
1ec10 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
1ec20 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
1ec30 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
1ec40 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
1ec50 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
1ec60 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
1ec70 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
1ec80 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
1ec90 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
1eca0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
1ecb0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
1ecc0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
1ecd0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
1ece0 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
1ecf0 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
1ed00 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
1ed10 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
1ed20 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
1ed30 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
1ed40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1ed50 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
1ed60 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
1ed70 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
1ed80 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
1ed90 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
1eda0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
1edb0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
1edc0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
1edd0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1ede0 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
1edf0 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
1ee00 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
1ee10 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
1ee20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
1ee30 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
1ee40 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
1ee50 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
1ee60 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20  E_ENABLE_STAT2] 
1ee70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1ee80 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
1ee90 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
1eea0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
1eeb0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1eec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1eed0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1eee0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1eef0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1ef00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1ef10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1ef20 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1ef30 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1ef40 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1ef50 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1ef60 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1ef70 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1ef80 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1ef90 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1efa0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1efb0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1efc0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1efd0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1efe0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1eff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1f000 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1f010 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1f020 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1f030 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f040 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1f050 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1f060 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1f070 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1f080 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1f090 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1f0a0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1f0b0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1f0c0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1f0d0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1f0e0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1f0f0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1f100 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1f110 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1f120 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1f130 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1f140 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1f150 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f160 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1f170 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1f180 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1f190 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1f1a0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1f1b0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1f1c0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1f1d0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1f1e0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1f1f0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1f200 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1f210 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1f220 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1f230 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1f240 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1f250 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1f260 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1f270 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1f280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f290 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1f2a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1f2b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1f2c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1f2d0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1f2e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1f2f0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1f300 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1f310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1f320 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1f330 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1f340 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1f350 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1f360 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1f370 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f380 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1f390 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1f3a0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1f3b0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1f3c0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1f3d0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1f3e0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
1f3f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
1f400 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1f410 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1f420 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1f430 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1f440 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1f450 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1f460 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1f470 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1f480 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1f490 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f4a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f4b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1f4c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1f4d0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1f4e0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1f4f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1f500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f510 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1f520 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
1f530 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
1f540 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
1f550 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
1f560 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
1f570 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
1f580 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
1f590 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
1f5a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f5b0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
1f5c0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
1f5d0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
1f5e0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1f5f0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
1f600 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
1f610 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1f620 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
1f630 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
1f640 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
1f650 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
1f660 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
1f670 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
1f680 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
1f690 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
1f6a0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
1f6b0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
1f6c0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
1f6d0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
1f6e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
1f6f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
1f700 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
1f710 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
1f720 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
1f730 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
1f740 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1f750 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
1f760 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
1f770 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
1f780 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1f790 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
1f7a0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
1f7b0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
1f7c0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
1f7d0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
1f7e0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
1f7f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
1f800 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
1f810 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
1f820 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
1f830 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
1f840 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
1f850 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
1f860 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
1f870 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
1f880 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
1f890 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
1f8a0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
1f8b0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
1f8c0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
1f8d0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
1f8e0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
1f8f0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
1f900 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
1f910 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
1f920 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
1f930 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
1f940 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
1f950 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
1f960 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
1f970 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
1f980 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
1f990 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
1f9a0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
1f9b0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
1f9c0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
1f9d0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
1f9e0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
1f9f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fa00 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
1fa10 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
1fa20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
1fa30 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1fa40 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
1fa50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
1fa60 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
1fa70 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1fa80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fa90 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
1faa0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
1fab0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1fac0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1fad0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
1fae0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1faf0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
1fb00 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
1fb10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
1fb20 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
1fb30 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
1fb40 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
1fb50 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1fb60 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
1fb70 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
1fb80 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
1fb90 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
1fba0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
1fbb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fbc0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
1fbd0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
1fbe0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
1fbf0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
1fc00 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
1fc10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1fc20 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
1fc30 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
1fc40 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
1fc50 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
1fc60 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
1fc70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1fc80 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
1fc90 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
1fca0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
1fcb0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
1fcc0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1fcd0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
1fce0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
1fcf0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
1fd00 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
1fd10 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
1fd20 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1fd30 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
1fd40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1fd50 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
1fd60 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
1fd70 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
1fd80 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
1fd90 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
1fda0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
1fdb0 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74    A internal mut
1fdc0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1fdd0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
1fde0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fdf0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
1fe00 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
1fe10 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1fe20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fe30 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
1fe40 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
1fe50 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
1fe60 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
1fe70 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
1fe80 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1fe90 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1fea0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1feb0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
1fec0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
1fed0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
1fee0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
1fef0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1ff00 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
1ff10 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1ff20 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
1ff30 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
1ff40 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1ff50 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1ff60 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1ff70 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
1ff80 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
1ff90 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
1ffa0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
1ffb0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
1ffc0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
1ffd0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1ffe0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
1fff0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
20000 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
20010 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20020 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
20030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
20040 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
20050 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
20060 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
20070 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
20080 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
20090 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
200a0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
200b0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
200c0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
200d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
200e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
200f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
20100 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
20110 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
20120 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
20130 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
20140 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
20150 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
20160 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20170 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
20180 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
20190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
201a0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
201b0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
201c0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
201d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
201e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
201f0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
20200 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
20210 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
20220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20230 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
20240 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
20250 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
20260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
20270 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
20280 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
20290 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
202a0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
202b0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
202c0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
202d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
202e0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
202f0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
20300 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
20310 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
20320 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
20330 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
20340 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
20350 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
20360 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
20370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
20380 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
20390 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
203a0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
203b0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
203c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
203d0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
203e0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
203f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
20400 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
20410 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
20420 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
20430 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
20440 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
20450 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
20460 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
20470 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
20480 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20490 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
204a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
204b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
204c0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
204d0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
204e0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
204f0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
20500 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
20510 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
20520 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
20530 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
20540 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
20550 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
20560 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
20570 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
20580 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
20590 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
205a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
205b0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
205c0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
205d0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
205e0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
205f0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
20600 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
20610 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
20620 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
20630 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
20640 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
20650 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
20660 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
20670 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
20680 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
20690 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
206a0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
206b0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
206c0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
206d0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
206e0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
206f0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
20700 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
20710 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
20720 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
20730 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
20740 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
20750 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
20760 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
20770 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
20780 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
20790 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
207a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
207b0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
207c0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
207d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
207e0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
207f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
20800 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
20810 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
20820 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
20830 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
20840 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
20850 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
20860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
20870 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
20880 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
20890 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
208a0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
208b0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
208c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
208d0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
208e0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
208f0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
20900 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
20910 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
20920 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
20930 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
20940 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
20950 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
20960 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
20970 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
20980 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20990 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
209a0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
209b0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
209c0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
209d0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
209e0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
209f0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
20a00 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
20a10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
20a20 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
20a30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
20a40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
20a50 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
20a60 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
20a70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
20a80 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
20a90 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
20aa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
20ab0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
20ac0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
20ad0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
20ae0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
20af0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
20b00 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
20b10 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
20b20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
20b30 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
20b40 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
20b50 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
20b60 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
20b70 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
20b80 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
20b90 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
20ba0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
20bb0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
20bc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20bd0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
20be0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
20bf0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
20c00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
20c10 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
20c20 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
20c30 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
20c40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
20c50 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
20c60 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
20c70 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
20c80 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
20c90 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
20ca0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
20cb0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
20cc0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
20cd0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
20ce0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
20cf0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
20d00 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
20d10 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
20d20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
20d30 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
20d40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
20d50 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
20d60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
20d70 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
20d80 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
20d90 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
20da0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
20db0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
20dc0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
20dd0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
20de0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
20df0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
20e00 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
20e10 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
20e20 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
20e30 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
20e40 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
20e50 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
20e60 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
20e70 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
20e80 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
20e90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
20ea0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20eb0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
20ec0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
20ed0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
20ee0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
20ef0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
20f00 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
20f10 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
20f20 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
20f30 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
20f40 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
20f50 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
20f60 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
20f70 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
20f80 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
20f90 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
20fa0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
20fb0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
20fc0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
20fd0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
20fe0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
20ff0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
21000 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
21010 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
21020 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
21030 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
21040 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
21050 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
21060 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
21070 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
21080 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
21090 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
210a0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
210b0 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
210c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
210d0 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
210e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
210f0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
21100 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
21110 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
21120 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
21130 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
21140 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
21150 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
21160 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
21170 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
21180 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
21190 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
211a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
211b0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
211c0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
211d0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
211e0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
211f0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
21200 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
21210 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
21220 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
21230 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
21240 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
21250 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
21260 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
21270 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
21280 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
21290 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
212a0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
212b0 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
212c0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
212d0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
212e0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
212f0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
21300 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
21310 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
21320 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
21330 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
21340 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
21350 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
21360 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21370 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21380 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
21390 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
213a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
213b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
213c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
213d0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
213e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
213f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21400 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
21410 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
21420 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
21430 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
21440 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21450 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
21460 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
21470 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
21480 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
21490 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
214a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
214b0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
214c0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
214d0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
214e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
214f0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
21500 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
21510 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
21520 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
21530 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
21540 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
21550 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
21560 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
21570 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
21580 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
21590 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
215a0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
215b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
215c0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
215d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
215e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
215f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21600 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
21610 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
21620 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
21630 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
21640 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
21650 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
21660 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
21670 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
21680 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21690 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
216a0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
216b0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
216c0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
216d0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
216e0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
216f0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
21700 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
21710 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
21720 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
21730 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
21740 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
21750 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
21760 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
21770 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
21780 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
21790 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
217a0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
217b0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
217c0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
217d0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
217e0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
217f0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
21800 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
21810 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
21820 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
21830 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
21840 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
21850 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
21860 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21870 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
21880 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
21890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
218a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
218b0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
218c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
218d0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
218e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
218f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
21910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21920 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
21930 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
21940 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
21950 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
21960 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
21970 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
21980 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
21990 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
219a0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
219b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
219c0 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
219d0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
219e0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
219f0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
21a00 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
21a10 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
21a20 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
21a30 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
21a40 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
21a50 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
21a60 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
21a70 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
21a80 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
21a90 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
21aa0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
21ab0 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
21ac0 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
21ad0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
21ae0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
21af0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
21b00 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
21b10 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
21b20 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
21b30 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
21b40 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
21b50 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
21b60 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
21b70 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
21b80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
21b90 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
21ba0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
21bb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
21bc0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
21bd0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
21be0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
21bf0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
21c00 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
21c10 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
21c20 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
21c30 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
21c40 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
21c50 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
21c60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21c70 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
21c80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21c90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
21ca0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
21cb0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
21cc0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
21cd0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21ce0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
21cf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21d00 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
21d10 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
21d20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
21d30 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21d40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21d50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
21d60 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
21d70 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
21d80 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
21d90 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
21da0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
21db0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
21dc0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
21dd0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
21de0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
21df0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
21e00 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
21e10 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
21e20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
21e30 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
21e40 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
21e50 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
21e60 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
21e70 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
21e80 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
21e90 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
21ea0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
21eb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
21ec0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
21ed0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
21ee0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
21ef0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21f00 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
21f10 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21f20 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
21f30 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
21f40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21f50 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
21f60 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
21f70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21f80 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
21f90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
21fa0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
21fb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
21fc0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
21fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21fe0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
21ff0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
22000 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
22010 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
22020 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
22030 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
22040 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
22050 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
22060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22070 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
22080 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22090 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
220a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
220b0 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
220c0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
220d0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
220e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
220f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
22100 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22110 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
22120 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
22130 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
22140 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
22150 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
22160 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
22170 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
22180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22190 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
221a0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
221b0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
221c0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
221d0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
221e0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
221f0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
22200 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
22210 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
22220 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
22230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
22240 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
22250 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
22260 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
22270 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
22280 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
22290 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
222a0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
222b0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
222c0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
222d0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
222e0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
222f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
22300 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22310 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
22320 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
22330 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
22340 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
22350 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
22360 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22370 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
22380 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
22390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
223a0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
223b0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
223c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
223d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
223e0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
223f0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
22400 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
22410 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22420 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
22430 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
22440 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
22450 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
22460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
22470 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
22480 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
22490 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
224a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
224b0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
224c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
224d0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
224e0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
224f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
22500 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
22510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22520 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
22530 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
22540 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
22550 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
22560 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
22570 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
22580 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
22590 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
225a0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
225b0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
225c0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
225d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
225e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
225f0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
22600 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
22610 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
22620 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
22630 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
22640 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
22650 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
22660 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
22670 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
22680 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
22690 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
226a0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
226b0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
226c0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
226d0 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
226e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
226f0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
22700 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
22710 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
22720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22730 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22740 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
22750 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
22760 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
22770 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
22780 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
22790 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
227a0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
227b0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
227c0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
227d0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
227e0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
227f0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
22800 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
22810 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
22820 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
22830 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
22840 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
22850 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
22860 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
22870 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
22880 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
22890 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
228a0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
228b0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
228c0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
228d0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
228e0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
228f0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
22900 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22910 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
22920 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
22930 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
22940 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
22950 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22960 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
22970 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
22980 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
22990 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
229a0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
229b0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
229c0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
229d0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
229e0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
229f0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
22a00 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
22a10 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
22a20 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
22a30 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
22a40 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
22a50 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
22a60 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
22a70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22a80 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
22a90 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
22aa0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
22ab0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
22ac0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
22ad0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
22ae0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
22af0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
22b00 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
22b10 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
22b20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
22b30 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
22b40 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
22b50 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
22b60 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
22b70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
22b80 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
22b90 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
22ba0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
22bb0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
22bc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
22bd0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
22be0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
22bf0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
22c00 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
22c10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
22c20 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
22c30 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
22c40 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
22c50 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
22c60 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
22c70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
22c80 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
22c90 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
22ca0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
22cb0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
22cc0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
22cd0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
22ce0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
22cf0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
22d00 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
22d10 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
22d20 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
22d30 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
22d40 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
22d50 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
22d60 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
22d70 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
22d80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
22d90 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
22da0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
22db0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
22dc0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
22dd0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
22de0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
22df0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
22e00 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
22e10 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
22e20 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
22e30 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
22e40 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
22e50 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
22e60 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
22e70 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
22e80 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
22e90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
22ea0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
22eb0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
22ec0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
22ed0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
22ee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22ef0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
22f00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
22f10 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
22f20 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22f30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
22f40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22f50 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
22f60 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
22f70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
22f80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22f90 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
22fa0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
22fb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
22fc0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22fd0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
22fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
22ff0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
23000 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23010 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
23020 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23030 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
23040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
23050 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
23060 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
23070 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
23080 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
23090 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
230a0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
230b0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
230c0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
230d0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
230e0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
230f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
23100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23110 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
23120 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
23130 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23140 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
23150 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
23160 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
23170 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
23180 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
23190 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
231a0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
231b0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
231c0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
231d0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
231e0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
231f0 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
23200 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
23210 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
23220 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
23230 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
23240 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
23250 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
23260 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
23270 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
23280 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
23290 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
232a0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
232b0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
232c0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
232d0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
232e0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
232f0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
23300 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
23310 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
23320 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
23330 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
23340 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
23350 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
23360 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
23370 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
23380 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
23390 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
233a0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
233b0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
233c0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
233d0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
233e0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
233f0 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
23400 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
23410 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
23420 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
23430 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
23440 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
23450 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
23460 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
23470 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
23480 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
23490 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
234a0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
234b0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
234c0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
234d0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
234e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
234f0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
23500 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
23510 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
23520 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
23530 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
23540 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
23550 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
23560 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23570 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
23580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
23590 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
235a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
235b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
235c0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
235d0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
235e0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
235f0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
23600 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
23610 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
23620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23630 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
23640 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
23650 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
23660 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
23670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23680 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
23690 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
236a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
236b0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
236c0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
236d0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
236e0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
236f0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
23700 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
23710 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
23720 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
23730 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
23740 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
23750 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
23760 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
23770 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
23780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23790 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
237a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
237b0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
237c0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
237d0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
237e0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
237f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
23800 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
23810 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
23820 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
23830 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
23840 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
23850 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
23860 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
23870 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
23880 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
23890 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
238a0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
238b0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
238c0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
238d0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
238e0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
238f0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
23900 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
23910 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
23920 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
23930 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
23940 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
23950 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
23960 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
23970 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
23980 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
23990 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
239a0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
239b0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
239c0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
239d0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
239e0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
239f0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
23a00 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
23a10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
23a20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
23a30 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
23a40 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
23a50 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
23a60 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
23a70 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
23a80 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
23a90 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
23aa0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
23ab0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
23ac0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
23ad0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
23ae0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
23af0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
23b00 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
23b10 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
23b20 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
23b30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
23b40 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
23b50 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
23b60 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
23b70 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
23b80 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
23b90 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
23ba0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
23bb0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
23bc0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
23bd0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
23be0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
23bf0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
23c00 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
23c10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
23c20 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
23c30 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
23c40 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
23c50 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
23c60 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
23c70 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
23c80 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
23c90 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
23ca0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
23cb0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
23cc0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
23cd0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
23ce0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
23cf0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
23d00 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
23d10 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
23d20 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
23d30 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
23d40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
23d50 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
23d60 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
23d70 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
23d80 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
23d90 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
23da0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
23db0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
23dc0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
23dd0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
23de0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
23df0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
23e00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
23e10 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
23e20 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
23e30 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
23e40 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
23e50 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
23e60 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
23e70 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
23e80 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
23e90 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
23ea0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
23eb0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
23ec0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23ed0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
23ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23ef0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
23f00 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
23f10 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
23f20 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
23f30 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
23f40 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
23f50 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
23f60 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
23f70 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
23f80 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
23f90 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
23fa0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
23fb0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
23fc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23fd0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
23fe0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
23ff0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
24000 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
24010 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
24020 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
24030 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
24040 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
24050 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
24060 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
24070 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
24080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24090 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
240a0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
240b0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
240c0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
240d0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
240e0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
240f0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
24100 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
24110 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
24120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
24130 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
24140 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
24150 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
24160 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
24170 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
24180 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
24190 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
241a0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
241b0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
241c0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
241d0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
241e0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
241f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24200 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
24210 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
24220 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
24230 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
24240 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
24250 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
24260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
24270 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
24280 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24290 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
242a0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
242b0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
242c0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
242d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
242e0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
242f0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
24300 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
24310 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
24320 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
24330 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
24340 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
24350 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
24360 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
24370 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
24380 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
24390 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
243a0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
243b0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
243c0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
243d0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
243e0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
243f0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
24400 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
24410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
24420 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
24430 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
24440 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
24450 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
24460 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
24470 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
24480 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
24490 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
244a0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
244b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
244c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
244d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
244e0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
244f0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
24500 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
24510 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
24520 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
24530 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
24540 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
24550 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
24560 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
24570 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
24580 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
24590 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
245a0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
245b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
245c0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
245d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
245e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
245f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
24600 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
24610 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
24620 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
24630 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
24640 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
24650 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
24660 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
24670 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
24680 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
24690 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
246a0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
246b0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
246c0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
246d0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
246e0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
246f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
24700 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
24710 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
24720 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
24730 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24740 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
24750 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24760 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
24770 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
24780 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
24790 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
247a0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
247b0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
247c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
247d0 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
247e0 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
247f0 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
24800 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
24810 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24820 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
24830 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
24840 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
24850 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
24860 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
24870 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
24880 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
24890 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
248a0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
248b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
248c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
248d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
248e0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
248f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
24900 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
24910 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
24920 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
24930 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
24940 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
24950 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
24960 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
24970 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
24980 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
24990 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
249a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
249b0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
249c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
249d0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
249e0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
249f0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
24a00 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
24a10 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
24a20 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
24a30 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
24a40 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
24a50 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
24a60 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
24a70 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
24a80 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
24a90 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
24aa0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
24ab0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
24ac0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
24ad0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
24ae0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
24af0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
24b00 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
24b10 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
24b20 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
24b30 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
24b40 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
24b50 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
24b60 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
24b70 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
24b80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
24b90 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
24ba0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
24bb0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
24bc0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
24bd0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
24be0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
24bf0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
24c00 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
24c10 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
24c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
24c30 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
24c40 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
24c50 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
24c60 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
24c70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24c80 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
24c90 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
24ca0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
24cb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
24cc0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
24cd0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
24ce0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
24cf0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
24d00 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
24d10 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
24d20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
24d30 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
24d40 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
24d50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
24d60 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
24d70 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
24d80 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
24d90 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
24da0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
24db0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
24dc0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
24dd0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
24de0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
24df0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
24e00 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
24e10 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
24e20 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
24e30 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
24e40 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
24e50 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
24e60 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
24e70 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
24e80 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
24e90 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
24ea0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
24eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24ec0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
24ed0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
24ee0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
24ef0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
24f00 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
24f10 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
24f20 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
24f30 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
24f40 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
24f50 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
24f60 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
24f70 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
24f80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
24f90 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
24fa0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
24fb0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
24fc0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
24fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
24fe0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
24ff0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
25000 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
25010 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
25020 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
25030 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
25040 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
25050 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
25060 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25070 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
25080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25090 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
250a0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
250b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
250c0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
250d0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
250e0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
250f0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
25100 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
25110 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25120 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
25130 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
25140 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
25150 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
25160 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
25170 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
25180 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
25190 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
251a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
251b0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
251c0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
251d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
251e0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
251f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
25200 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
25210 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
25220 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
25230 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
25240 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
25250 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
25260 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
25270 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
25280 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
25290 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
252a0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
252b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
252c0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
252d0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
252e0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
252f0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
25300 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
25310 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
25320 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
25330 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
25340 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
25350 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
25360 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
25370 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
25380 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
25390 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
253a0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
253b0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
253c0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
253d0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
253e0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
253f0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
25400 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
25410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25420 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
25430 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
25440 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25450 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
25460 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
25470 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
25480 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
25490 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
254a0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
254b0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
254c0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
254d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
254e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
254f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
25500 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
25510 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
25520 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
25530 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
25540 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
25550 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
25560 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
25570 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
25580 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
25590 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
255a0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
255b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
255c0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
255d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
255e0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
255f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
25600 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
25610 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
25620 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
25630 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
25640 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
25650 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
25660 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
25670 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
25680 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25690 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
256a0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
256b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
256c0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
256d0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
256e0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
256f0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
25700 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
25710 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
25720 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
25730 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
25740 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
25750 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
25760 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
25770 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
25780 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
25790 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
257a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
257b0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
257c0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
257d0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
257e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
257f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
25800 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
25810 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
25820 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
25830 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
25840 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
25850 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
25860 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
25870 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
25880 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
25890 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
258a0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
258b0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
258c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
258d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
258e0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
258f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25900 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
25910 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
25920 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
25930 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
25940 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
25950 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
25960 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
25970 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
25980 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
25990 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
259a0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
259b0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
259c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
259d0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
259e0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
259f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
25a00 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
25a10 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
25a20 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
25a30 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
25a40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
25a50 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
25a60 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
25a70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25a80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
25a90 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
25aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25ab0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
25ac0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
25ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
25ae0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25af0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
25b00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
25b10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25b20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
25b30 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
25b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
25b50 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
25b60 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
25b70 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
25b80 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
25b90 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
25ba0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
25bb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
25bc0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
25bd0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
25be0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
25bf0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
25c00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
25c10 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
25c20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
25c30 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
25c40 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
25c50 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
25c60 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
25c70 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
25c80 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
25c90 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
25ca0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
25cb0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
25cc0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
25cd0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
25ce0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
25cf0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
25d00 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
25d10 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
25d20 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
25d30 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
25d40 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
25d50 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
25d60 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
25d70 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
25d80 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
25d90 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
25da0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
25db0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
25dc0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
25dd0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
25de0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
25df0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
25e00 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
25e10 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
25e20 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
25e30 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
25e40 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
25e50 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
25e60 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
25e70 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
25e80 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
25e90 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
25ea0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
25eb0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
25ec0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
25ed0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
25ee0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
25ef0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
25f00 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
25f10 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
25f20 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
25f30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
25f40 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
25f50 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
25f60 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
25f70 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
25f80 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
25f90 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
25fa0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
25fb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
25fc0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
25fd0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
25fe0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
25ff0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
26000 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
26010 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
26020 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
26030 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
26040 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
26050 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
26060 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
26070 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
26080 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
26090 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
260a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
260b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
260c0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
260d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
260e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
260f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
26100 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
26110 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
26120 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
26130 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
26140 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
26150 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
26160 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
26170 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
26180 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
26190 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
261a0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
261b0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
261c0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
261d0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
261e0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
261f0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
26200 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
26210 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
26220 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
26230 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
26240 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
26250 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
26260 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
26270 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
26280 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
26290 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
262a0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
262b0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
262c0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
262d0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
262e0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
262f0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
26300 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
26310 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
26320 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
26330 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
26340 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
26350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26360 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
26370 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
26380 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
26390 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
263a0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
263b0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
263c0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
263d0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
263e0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
263f0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
26400 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
26410 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
26420 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
26430 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
26440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26450 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
26460 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26470 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
26480 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
26490 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
264a0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
264b0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
264c0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
264d0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
264e0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
264f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
26500 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
26510 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
26520 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
26530 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
26540 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
26550 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
26560 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
26570 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
26580 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
26590 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
265a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
265b0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
265c0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
265d0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
265e0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
265f0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
26600 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
26610 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
26620 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
26630 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
26640 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
26650 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
26660 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
26670 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
26680 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
26690 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
266a0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
266b0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
266c0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
266d0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
266e0 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
266f0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
26700 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
26710 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
26720 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
26730 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
26740 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
26750 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
26760 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
26770 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
26780 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
26790 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
267a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
267b0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
267c0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
267d0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
267e0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
267f0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
26800 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
26810 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
26820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26830 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
26840 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
26850 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
26860 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
26870 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
26880 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
26890 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
268a0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
268b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
268c0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
268d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
268e0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
268f0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
26900 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
26910 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
26920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26930 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
26940 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
26950 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26960 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
26970 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
26980 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
26990 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
269a0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
269b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
269c0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
269d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
269e0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
269f0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
26a00 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
26a10 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
26a20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
26a30 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
26a40 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
26a50 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
26a60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
26a70 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
26a80 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
26a90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26aa0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
26ab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
26ac0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
26ad0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
26ae0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
26af0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
26b00 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
26b10 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
26b20 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
26b30 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
26b40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
26b50 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
26b60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26b70 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
26b80 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
26b90 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
26ba0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
26bb0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
26bc0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
26bd0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
26be0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
26bf0 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
26c00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
26c10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26c20 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
26c30 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
26c40 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
26c50 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
26c60 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
26c70 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
26c80 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
26c90 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
26ca0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
26cb0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
26cc0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
26cd0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
26ce0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
26cf0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
26d00 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
26d10 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
26d20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
26d30 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
26d40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
26d50 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
26d60 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
26d70 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
26d80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26d90 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
26da0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26db0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
26dc0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
26dd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26de0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
26df0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
26e00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26e10 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
26e20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
26e30 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
26e40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
26e50 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
26e60 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
26e70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26e80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
26e90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
26ea0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
26eb0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
26ec0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
26ed0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26ee0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
26ef0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26f00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
26f20 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
26f30 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
26f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26f50 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
26f60 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
26f70 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
26f80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
26f90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26fa0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
26fb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
26fc0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
26fd0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
26fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26ff0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
27000 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
27010 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
27020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27030 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
27040 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
27050 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
27060 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
27070 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a  ed no errors or.
27080 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
27090 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
270a0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
270b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
270c0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
270d0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
270e0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
270f0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
27100 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
27110 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
27120 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
27130 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
27140 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
27150 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
27160 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
27170 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
27180 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
27190 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
271a0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
271b0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
271c0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
271d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
271e0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
271f0 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
27200 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
27210 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
27220 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
27230 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27240 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
27250 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
27260 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
27270 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
27280 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
27290 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
272a0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
272b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
272c0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
272d0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
272e0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
272f0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
27300 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
27310 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
27320 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
27330 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
27340 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
27350 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
27360 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
27370 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
27380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
27390 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
273a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
273b0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
273c0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
273d0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
273e0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
273f0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
27400 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
27410 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
27420 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
27430 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
27440 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
27450 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
27460 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
27470 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
27480 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
27490 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
274a0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
274b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
274c0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
274d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
274e0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
274f0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
27500 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
27510 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
27520 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
27530 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
27540 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
27550 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
27560 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
27570 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
27580 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
27590 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
275a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
275b0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
275c0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
275d0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
275e0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
275f0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
27600 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
27610 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
27620 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
27630 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
27640 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
27650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27660 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
27670 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
27680 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
27690 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
276a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
276b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
276c0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
276d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
276e0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
276f0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
27700 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
27710 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
27720 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
27730 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
27740 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
27750 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
27760 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
27770 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
27780 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
27790 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
277a0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
277b0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
277c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
277d0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
277e0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
277f0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
27800 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
27810 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
27820 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
27830 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
27840 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
27850 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
27860 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
27870 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27880 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
27890 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
278a0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
278b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
278c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
278d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
278e0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
278f0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
27900 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
27910 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
27920 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
27930 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
27940 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
27950 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27960 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
27970 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
27980 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27990 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
279a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
279b0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
279c0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
279d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
279e0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
279f0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
27a00 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
27a10 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
27a20 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
27a30 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
27a40 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
27a50 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
27a60 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
27a70 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
27a80 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
27a90 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
27aa0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
27ab0 65 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  e the second par
27ac0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
27ad0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
27ae0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
27af0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
27b00 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
27b10 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
27b20 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
27b30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
27b40 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
27b50 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
27b60 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
27b70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27b80 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
27b90 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
27ba0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
27bb0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
27bc0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
27bd0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
27be0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
27bf0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
27c00 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27c10 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
27c20 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
27c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27c40 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
27c50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
27c60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
27c70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
27c80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
27c90 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
27ca0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
27cb0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
27cc0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
27cd0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
27ce0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
27cf0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
27d00 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
27d10 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
27d20 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
27d30 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
27d40 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
27d50 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
27d60 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
27d70 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
27d80 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
27d90 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
27da0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
27db0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
27dc0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
27dd0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
27de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
27df0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
27e00 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
27e10 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
27e20 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
27e30 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
27e40 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
27e50 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
27e60 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
27e70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
27e80 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
27e90 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
27ea0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
27eb0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
27ec0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
27ed0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
27ee0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
27ef0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
27f00 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
27f10 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
27f20 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
27f30 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
27f40 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27f50 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
27f60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
27f70 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
27f80 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
27f90 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
27fa0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
27fb0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
27fc0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
27fd0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
27fe0 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
27ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
28010 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
28020 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
28030 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
28040 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
28050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28060 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
28070 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
28080 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
28090 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
280a0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
280b0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
280c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
280d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
280e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
280f0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
28100 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
28110 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
28120 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
28130 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
28140 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
28150 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
28160 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
28170 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
28180 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
28190 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
281a0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
281b0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
281c0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
281d0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
281e0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
281f0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
28200 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
28210 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
28220 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
28230 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
28240 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
28250 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
28260 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
28270 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
28280 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
28290 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
282a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
282b0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
282c0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
282d0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
282e0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
282f0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
28300 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
28310 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
28320 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
28330 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
28340 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
28350 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
28360 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
28370 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
28380 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
28390 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
283a0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
283b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
283c0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
283d0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
283e0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
283f0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
28400 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
28410 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
28420 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
28430 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
28440 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
28450 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
28460 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28470 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
28480 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
28490 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
284a0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
284b0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
284c0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
284d0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
284e0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
284f0 20 70 6f 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c   poiners for all
28500 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
28510 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
28520 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
28530 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28540 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28550 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
28560 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
28570 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
28580 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
28590 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
285a0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
285b0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
285c0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
285d0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
285e0 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
285f0 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
28600 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
28610 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
28620 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
28630 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
28640 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
28650 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
28660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28670 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
28680 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
28690 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
286a0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
286b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
286c0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
286d0 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
286e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
286f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
28700 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
28710 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
28720 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
28730 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28740 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28750 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
28760 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
28770 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
28780 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
28790 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
287a0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
287b0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
287c0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
287d0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
287e0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
287f0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
28800 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
28810 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
28820 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
28830 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
28840 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
28850 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
28860 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
28870 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
28880 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
28890 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
288a0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
288b0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
288c0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
288d0 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
288e0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
288f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28900 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
28910 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
28920 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
28930 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
28940 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
28950 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
28960 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
28970 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
28980 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
28990 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
289a0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
289b0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
289c0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
289d0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
289e0 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
289f0 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
28a00 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
28a10 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
28a20 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
28a30 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
28a40 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
28a50 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
28a60 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
28a70 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
28a80 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
28a90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28aa0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
28ab0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
28ac0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28ad0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
28ae0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
28af0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
28b00 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
28b10 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
28b20 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
28b30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
28b40 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
28b50 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
28b60 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
28b70 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
28b80 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
28b90 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
28ba0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28bb0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
28bc0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
28bd0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
28be0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
28bf0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
28c00 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
28c10 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
28c20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
28c30 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
28c40 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
28c50 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
28c60 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
28c70 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
28c80 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
28c90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
28ca0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
28cb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
28cc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
28cd0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
28ce0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
28cf0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
28d00 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
28d10 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
28d20 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
28d30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
28d40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
28d50 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
28d60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
28d70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
28d80 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
28d90 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
28da0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
28db0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28dc0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
28dd0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
28de0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
28df0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
28e00 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
28e10 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
28e20 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
28e30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28e40 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
28e50 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
28e60 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
28e70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
28e80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
28e90 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
28ea0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28eb0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
28ec0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
28ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28ee0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
28ef0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
28f00 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
28f10 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
28f20 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
28f30 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
28f40 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
28f50 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
28f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28f70 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
28f80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28f90 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
28fa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28fb0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
28fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28fd0 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
28fe0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
28ff0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
29000 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
29010 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
29020 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
29030 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
29040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
29050 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
29060 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
29070 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29080 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
29090 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
290a0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
290b0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
290c0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
290d0 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
290e0 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
290f0 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
29100 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
29110 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
29120 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
29130 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
29140 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
29150 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
29160 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
29170 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
29180 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
29190 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
291a0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
291b0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
291c0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
291d0 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
291e0 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
291f0 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
29200 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
29210 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
29220 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
29230 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
29240 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29250 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
29260 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
29270 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
29280 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
29290 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
292a0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
292b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
292c0 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
292d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
292e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
292f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
29300 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
29310 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
29320 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
29330 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
29340 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
29350 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
29360 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
29370 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
29380 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
29390 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
293a0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
293b0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
293c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
293d0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
293e0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
293f0 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
29400 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
29410 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
29420 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
29430 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
29440 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
29450 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
29460 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
29470 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
29480 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
29490 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
294a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
294b0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
294c0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
294d0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
294e0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
294f0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
29500 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
29510 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
29520 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29530 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
29540 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
29550 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
29560 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
29570 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
29580 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29590 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
295a0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
295b0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
295c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
295d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
295e0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
295f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29600 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
29610 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29620 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
29630 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
29640 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
29650 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
29660 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
29670 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
29680 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
29690 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
296a0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
296b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
296c0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
296d0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
296e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
296f0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
29700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
29710 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
29720 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
29730 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
29740 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
29750 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
29760 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
29770 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
29780 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
29790 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
297a0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
297b0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
297c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
297d0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
297e0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
297f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
29800 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
29810 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
29820 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
29830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
29840 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
29850 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
29860 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
29870 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
29880 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
29890 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
298a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
298b0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
298c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
298d0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
298e0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
298f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
29900 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
29910 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
29920 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
29930 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
29940 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
29950 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
29960 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
29970 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
29980 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
29990 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
299a0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
299b0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
299c0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
299d0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
299e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
299f0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
29a00 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
29a10 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
29a20 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
29a30 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
29a40 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
29a50 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
29a60 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
29a70 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
29a80 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
29a90 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
29aa0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
29ab0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
29ac0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
29ad0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
29ae0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
29af0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
29b00 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
29b10 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
29b20 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
29b30 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
29b40 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
29b50 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
29b60 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
29b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29b80 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
29b90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29ba0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
29bb0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
29bc0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
29bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
29be0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
29bf0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
29c00 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
29c10 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
29c20 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
29c30 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
29c40 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
29c50 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
29c60 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
29c70 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
29c80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
29c90 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
29ca0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
29cb0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
29cc0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29cd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
29ce0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29cf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
29d00 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
29d10 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
29d20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
29d30 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
29d40 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
29d50 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
29d60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29d70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
29d80 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
29d90 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
29da0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
29db0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
29dc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
29dd0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
29de0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
29df0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
29e00 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
29e10 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
29e20 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
29e30 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
29e40 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
29e50 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
29e60 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
29e70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
29e80 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
29e90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
29ea0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
29eb0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
29ec0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29ed0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
29ee0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
29ef0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
29f00 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
29f10 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
29f20 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
29f30 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
29f40 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
29f50 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
29f60 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
29f70 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
29f80 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
29f90 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
29fa0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
29fb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
29fc0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
29fd0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
29fe0 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
29ff0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
2a000 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
2a010 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
2a020 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
2a030 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
2a040 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2a050 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
2a060 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
2a070 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
2a080 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2a090 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2a0a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2a0b0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2a0c0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2a0d0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
2a0e0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2a0f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2a100 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
2a110 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
2a120 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
2a130 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2a140 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
2a150 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
2a160 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
2a170 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
2a180 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
2a190 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
2a1a0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
2a1b0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
2a1c0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
2a1d0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
2a1e0 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
2a1f0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
2a200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
2a210 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
2a220 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
2a230 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
2a240 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
2a250 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
2a260 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2a270 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
2a280 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
2a290 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
2a2a0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
2a2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a2c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2a2d0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2a2e0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
2a2f0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
2a300 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
2a310 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
2a320 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
2a330 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
2a340 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
2a350 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
2a360 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
2a370 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2a380 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
2a390 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
2a3a0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
2a3b0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
2a3c0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
2a3d0 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
2a3e0 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
2a3f0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2a400 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2a410 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
2a420 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
2a430 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2a440 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
2a450 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
2a460 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
2a470 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
2a480 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2a490 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
2a4a0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
2a4b0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2a4c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2a4d0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2a4e0 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
2a4f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2a500 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
2a510 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
2a520 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2a530 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2a540 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2a550 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2a560 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2a570 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
2a580 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
2a590 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2a5a0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2a5b0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2a5c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2a5d0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2a5e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2a5f0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2a600 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2a610 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2a620 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2a630 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2a640 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2a650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a660 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2a670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2a680 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2a690 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2a6a0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
2a6b0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2a6c0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2a6d0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
2a6e0 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
2a6f0 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
2a700 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
2a710 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2a720 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a730 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2a740 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2a750 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2a760 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2a770 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2a780 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2a790 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2a7a0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2a7b0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2a7c0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2a7d0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2a7e0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2a7f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a800 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2a810 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2a820 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2a830 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2a840 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2a850 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2a860 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2a870 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2a880 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
2a890 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2a8a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a8b0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2a8c0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
2a8d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2a8e0 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
2a8f0 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
2a900 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2a910 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a920 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2a930 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a940 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2a950 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2a960 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2a970 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2a980 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2a990 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2a9a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2a9b0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2a9c0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2a9d0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2a9e0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2a9f0 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
2aa00 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2aa10 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2aa20 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2aa30 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2aa40 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2aa50 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2aa60 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2aa70 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2aa80 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2aa90 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2aaa0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2aab0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2aac0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2aad0 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2aae0 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2aaf0 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2ab00 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2ab10 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2ab20 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2ab30 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2ab40 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2ab50 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2ab60 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2ab70 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2ab80 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2ab90 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2aba0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2abb0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2abc0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2abd0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2abe0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2abf0 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2ac00 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2ac10 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2ac20 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2ac30 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2ac40 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2ac50 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2ac60 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2ac70 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2ac80 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2ac90 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2aca0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2acb0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2acc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2acd0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2ace0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2acf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ad00 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2ad10 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2ad20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2ad30 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2ad40 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2ad50 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2ad60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ad70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ad80 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
2ad90 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2ada0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2adb0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2adc0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2add0 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2ade0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2adf0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2ae00 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2ae10 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2ae20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2ae30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2ae40 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2ae50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2ae60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ae70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2ae80 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2ae90 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2aea0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2aeb0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2aec0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2aed0 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2aee0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2aef0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2af00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2af10 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2af20 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2af30 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2af40 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2af50 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2af60 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2af70 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
2af80 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2af90 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2afa0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2afb0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2afc0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2afd0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2afe0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2aff0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2b000 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2b010 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2b020 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2b030 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2b040 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2b050 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2b060 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2b070 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2b080 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2b090 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2b0a0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2b0b0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2b0c0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2b0d0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2b0e0 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
2b0f0 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
2b100 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2b110 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
2b120 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
2b130 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
2b140 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
2b150 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2b160 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2b170 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2b180 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2b190 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2b1a0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2b1b0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2b1c0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2b1d0 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
2b1e0 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
2b1f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b200 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2b210 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2b220 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2b230 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2b240 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2b250 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2b260 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2b270 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2b280 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2b290 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2b2a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2b2b0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2b2c0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2b2d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b2e0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2b2f0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2b300 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
2b310 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2b320 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
2b330 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
2b340 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2b350 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
2b360 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
2b370 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2b380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2b390 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
2b3a0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2b3b0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2b3c0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2b3d0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2b3e0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2b3f0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2b400 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2b410 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2b420 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2b430 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
2b440 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2b450 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2b460 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2b470 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2b480 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2b490 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2b4a0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2b4b0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2b4c0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2b4d0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2b4e0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2b4f0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2b500 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2b510 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2b520 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2b530 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2b540 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2b550 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2b560 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2b570 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2b580 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2b590 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2b5a0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2b5b0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2b5c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2b5d0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2b5e0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2b5f0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2b600 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2b610 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2b620 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
2b630 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b640 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2b650 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2b660 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2b670 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2b680 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2b690 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2b6a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2b6b0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2b6c0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2b6d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2b6e0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2b6f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2b700 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2b710 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2b720 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
2b730 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
2b740 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
2b750 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
2b760 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
2b770 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
2b780 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
2b790 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
2b7a0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
2b7b0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
2b7c0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2b7d0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2b7e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b7f0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2b800 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2b810 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2b820 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2b830 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b840 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2b850 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2b860 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2b870 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2b880 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2b890 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2b8a0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2b8b0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2b8c0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2b8d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b8e0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2b8f0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2b900 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2b910 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b920 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2b930 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2b940 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2b950 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2b960 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2b970 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2b980 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2b990 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2b9a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b9b0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
2b9c0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2b9d0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2b9e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b9f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ba00 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
2ba10 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
2ba20 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
2ba30 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2ba40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2ba50 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2ba60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ba70 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
2ba80 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
2ba90 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
2baa0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
2bab0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
2bac0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2bad0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2bae0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2baf0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2bb00 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2bb10 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2bb20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2bb30 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2bb40 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2bb50 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
2bb60 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2bb70 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2bb80 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2bb90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2bba0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
2bbb0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2bbc0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2bbd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2bbe0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2bbf0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2bc00 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
2bc10 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
2bc20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2bc30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2bc40 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2bc50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2bc60 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
2bc70 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2bc80 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
2bc90 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
2bca0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
2bcb0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2bcc0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2bcd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2bce0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2bcf0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
2bd00 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2bd10 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
2bd20 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
2bd30 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
2bd40 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
2bd50 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2bd60 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2bd70 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
2bd80 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2bd90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2bda0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2bdb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bdc0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
2bdd0 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
2bde0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2bdf0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2be00 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
2be10 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
2be20 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
2be30 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
2be40 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
2be50 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
2be60 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
2be70 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2be80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2be90 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2bea0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2beb0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2bec0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2bed0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2bee0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2bef0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
2bf00 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2bf10 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2bf20 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2bf30 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
2bf40 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
2bf50 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2bf60 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2bf70 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
2bf80 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
2bf90 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
2bfa0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
2bfb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
2bfc0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
2bfd0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2bfe0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2bff0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2c000 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
2c010 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
2c020 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
2c030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c040 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
2c050 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2c060 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2c070 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2c080 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
2c090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c0a0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
2c0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2c0c0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2c0d0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2c0e0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2c0f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c100 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c110 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2c120 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2c130 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2c140 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2c150 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
2c160 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2c170 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2c180 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2c190 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2c1a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c1b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2c1c0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2c1d0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2c1e0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2c1f0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2c200 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c210 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
2c220 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2c230 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2c240 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2c250 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c260 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
2c270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c280 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2c290 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
2c2a0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
2c2b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2c2c0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
2c2d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c2e0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
2c2f0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
2c300 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2c310 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c320 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c330 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
2c340 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
2c350 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
2c360 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
2c370 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
2c380 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2c390 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
2c3a0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
2c3b0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2c3c0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
2c3d0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2c3e0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2c3f0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2c400 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2c410 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2c420 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2c430 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
2c440 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2c450 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2c460 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2c470 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
2c480 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
2c490 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
2c4a0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
2c4b0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
2c4c0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2c4d0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2c4e0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2c4f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2c500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c510 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2c520 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
2c530 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
2c540 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2c550 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
2c560 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
2c570 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2c580 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
2c590 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
2c5a0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
2c5b0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
2c5c0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
2c5d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2c5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c5f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2c600 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2c610 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
2c620 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
2c630 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
2c640 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
2c650 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
2c660 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
2c670 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2c680 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2c690 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2c6a0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2c6b0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2c6c0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2c6d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2c6e0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
2c6f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2c700 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2c710 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2c720 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2c730 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
2c740 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2c750 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2c760 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
2c770 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
2c780 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
2c790 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2c7a0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
2c7b0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2c7c0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
2c7d0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
2c7e0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2c7f0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2c800 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2c810 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2c820 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2c830 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2c840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c850 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2c860 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2c870 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2c880 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2c890 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2c8a0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2c8b0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2c8c0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2c8d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2c8e0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2c8f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c900 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2c910 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2c920 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2c930 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c940 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c950 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2c960 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2c970 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c980 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2c990 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2c9a0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
2c9b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c9c0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2c9d0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2c9e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
2c9f0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
2ca00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2ca10 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
2ca20 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
2ca30 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
2ca40 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2ca50 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
2ca60 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
2ca70 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
2ca80 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
2ca90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2caa0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
2cab0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
2cac0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
2cad0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cae0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
2caf0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
2cb00 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
2cb10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cb20 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
2cb30 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
2cb40 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
2cb50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2cb60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
2cb70 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
2cb80 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
2cb90 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
2cba0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
2cbb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2cbc0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
2cbd0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
2cbe0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
2cbf0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
2cc00 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2cc10 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2cc20 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
2cc30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2cc40 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2cc50 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2cc60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2cc70 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
2cc80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
2cc90 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
2cca0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ccb0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
2ccc0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2ccd0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2cce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ccf0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2cd00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2cd10 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2cd20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2cd30 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
2cd40 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2cd50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cd60 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
2cd70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2cd80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2cd90 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
2cda0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2cdb0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2cdc0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
2cdd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2cde0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2cdf0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2ce00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ce10 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2ce20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2ce30 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
2ce40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2ce50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ce60 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
2ce70 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2ce80 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
2ce90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2cea0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ceb0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
2cec0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2ced0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2cee0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2cef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cf00 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2cf10 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2cf20 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2cf30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2cf40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2cf50 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2cf60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2cf70 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2cf80 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2cf90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2cfa0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
2cfb0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2cfc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
2cfd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2cfe0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2cff0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
2d000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d010 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
2d020 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
2d030 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
2d040 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
2d050 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
2d060 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
2d070 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2d080 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2d090 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
2d0a0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
2d0b0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
2d0c0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2d0d0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
2d0e0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2d0f0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2d100 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2d110 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2d120 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2d130 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2d140 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
2d150 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
2d160 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2d170 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2d180 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
2d190 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
2d1a0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
2d1b0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
2d1c0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
2d1d0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
2d1e0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
2d1f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
2d200 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
2d210 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
2d220 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
2d230 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
2d240 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2d250 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
2d260 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
2d270 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2d280 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
2d290 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2d2a0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
2d2b0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2d2c0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
2d2d0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
2d2e0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
2d2f0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
2d300 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
2d310 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
2d320 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2d330 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
2d340 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
2d350 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
2d360 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2d370 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
2d380 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
2d390 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
2d3a0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
2d3b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2d3c0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
2d3d0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
2d3e0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
2d3f0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
2d400 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
2d410 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
2d420 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
2d430 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2d440 20 70 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c   pArg, is a appl
2d450 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2d460 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
2d470 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
2d480 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2d490 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
2d4a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2d4b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2d4c0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2d4d0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
2d4e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d4f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2d500 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
2d510 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
2d520 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
2d530 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2d540 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2d550 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
2d560 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
2d570 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
2d580 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
2d590 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
2d5a0 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
2d5b0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2d5c0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
2d5d0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
2d5e0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
2d5f0 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
2d600 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2d610 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
2d620 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
2d630 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d640 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
2d650 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
2d660 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
2d670 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
2d680 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
2d690 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
2d6a0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
2d6b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
2d6c0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
2d6d0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
2d6e0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2d6f0 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
2d700 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2d710 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2d720 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
2d730 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
2d740 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
2d750 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
2d760 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
2d770 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
2d780 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
2d790 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
2d7a0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2d7b0 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
2d7c0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
2d7d0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
2d7e0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2d7f0 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
2d800 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
2d810 61 79 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ay return the sa
2d820 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
2d830 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
2d840 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
2d850 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
2d860 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
2d870 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
2d880 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
2d890 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
2d8a0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
2d8b0 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
2d8c0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
2d8d0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
2d8e0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
2d8f0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
2d900 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
2d910 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d920 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
2d930 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
2d940 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
2d950 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
2d960 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
2d970 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
2d980 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
2d990 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
2d9a0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
2d9b0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
2d9c0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
2d9d0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
2d9e0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
2d9f0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
2da00 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
2da10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
2da20 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
2da30 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
2da40 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
2da50 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2da60 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
2da70 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
2da80 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
2da90 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
2daa0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2dab0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2dac0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2dad0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2dae0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2daf0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
2db00 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
2db10 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
2db20 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2db30 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
2db40 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2db50 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2db60 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
2db70 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
2db80 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
2db90 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
2dba0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
2dbb0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
2dbc0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
2dbd0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
2dbe0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2dbf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2dc00 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2dc10 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2dc20 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
2dc30 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
2dc40 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
2dc50 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
2dc60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2dc70 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
2dc80 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
2dc90 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
2dca0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
2dcb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2dcc0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
2dcd0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
2dce0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
2dcf0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
2dd00 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
2dd10 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
2dd20 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2dd30 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
2dd40 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
2dd50 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
2dd60 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
2dd70 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
2dd80 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
2dd90 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
2dda0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
2ddb0 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
2ddc0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
2ddd0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
2dde0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
2ddf0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
2de00 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
2de10 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
2de20 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
2de30 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2de40 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
2de50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2de60 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
2de70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2de80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
2de90 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2dea0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2deb0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2dec0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
2ded0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2dee0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2def0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2df00 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2df10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2df20 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2df30 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2df40 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2df50 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2df60 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
2df70 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2df80 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2df90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2dfa0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
2dfb0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
2dfc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2dfd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2dfe0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2dff0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
2e000 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
2e010 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
2e020 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
2e030 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2e040 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2e050 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2e060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e070 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2e080 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2e090 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
2e0a0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2e0b0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2e0c0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2e0d0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2e0e0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2e0f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2e100 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2e110 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2e120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e130 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
2e140 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
2e150 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2e160 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2e170 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2e180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
2e190 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2e1a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2e1b0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2e1c0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2e1d0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2e1e0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2e1f0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2e200 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2e210 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2e220 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
2e230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2e240 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2e250 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
2e260 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
2e270 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2e280 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2e290 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
2e2a0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
2e2b0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
2e2c0 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
2e2d0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
2e2e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
2e2f0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
2e300 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2e310 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
2e320 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
2e330 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
2e340 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2e350 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2e360 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
2e370 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e380 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
2e390 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2e3a0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
2e3b0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
2e3c0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2e3d0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2e3e0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2e3f0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2e400 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
2e410 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2e420 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
2e430 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
2e440 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2e450 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2e460 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
2e470 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2e480 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2e490 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
2e4a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2e4b0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
2e4c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2e4d0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2e4e0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2e4f0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2e500 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e510 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2e520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e530 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2e540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2e550 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e560 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2e570 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2e580 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
2e590 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
2e5a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2e5b0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2e5c0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
2e5d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e5e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2e5f0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2e600 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
2e610 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2e620 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2e630 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2e640 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
2e650 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
2e660 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
2e670 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
2e680 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
2e690 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
2e6a0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
2e6b0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
2e6c0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
2e6d0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2e6e0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2e6f0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2e700 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2e710 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2e720 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e730 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2e740 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2e750 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2e760 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2e770 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2e780 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2e790 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
2e7a0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
2e7b0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
2e7c0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
2e7d0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
2e7e0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
2e7f0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
2e800 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
2e810 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
2e820 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
2e830 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
2e840 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
2e850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2e860 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2e870 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2e880 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2e890 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2e8a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2e8b0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
2e8c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e8e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2e8f0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2e900 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2e910 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2e920 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
2e930 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
2e940 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2e950 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
2e960 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
2e970 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2e980 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
2e990 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
2e9a0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2e9b0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2e9c0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2e9d0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2e9e0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2e9f0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2ea00 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2ea10 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2ea20 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2ea30 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2ea40 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2ea50 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2ea60 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2ea70 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2ea80 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2ea90 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2eaa0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2eab0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
2eac0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2ead0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2eae0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2eaf0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
2eb00 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
2eb10 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
2eb20 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
2eb30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2eb40 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2eb50 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
2eb60 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2eb70 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2eb80 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2eb90 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2eba0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2ebb0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2ebc0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
2ebd0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2ebe0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
2ebf0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
2ec00 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
2ec10 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
2ec20 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
2ec30 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
2ec40 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
2ec50 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
2ec60 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
2ec70 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
2ec80 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2ec90 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
2eca0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2ecb0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
2ecc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
2ecd0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2ece0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2ecf0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2ed00 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2ed10 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2ed20 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2ed30 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
2ed40 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
2ed50 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
2ed60 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
2ed70 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
2ed80 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
2ed90 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
2eda0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2edb0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
2edc0 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
2edd0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
2ede0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
2edf0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
2ee00 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2ee10 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
2ee20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2ee30 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2ee40 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2ee50 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
2ee60 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
2ee70 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
2ee80 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
2ee90 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
2eea0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
2eeb0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
2eec0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2eed0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2eee0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2eef0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
2ef00 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
2ef10 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2ef20 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
2ef30 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2ef40 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
2ef50 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2ef60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2ef70 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2ef80 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2ef90 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2efa0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2efb0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2efc0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2efd0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2efe0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2eff0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2f000 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2f010 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2f020 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2f030 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2f040 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2f050 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2f060 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2f070 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2f080 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2f090 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2f0a0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2f0b0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2f0c0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2f0d0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2f0e0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2f0f0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2f100 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2f110 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2f120 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2f130 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2f140 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2f150 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2f160 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2f170 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2f180 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2f190 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2f1a0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2f1b0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2f1c0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2f1d0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2f1e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2f1f0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2f200 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2f210 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2f220 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2f230 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2f240 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2f250 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2f260 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2f270 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2f280 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2f290 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2f2a0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2f2b0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2f2c0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2f2d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2f2e0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2f2f0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2f300 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2f310 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2f320 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2f330 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2f340 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2f350 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2f360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2f370 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2f380 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2f390 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2f3a0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2f3b0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2f3c0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2f3d0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2f3e0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2f3f0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2f400 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2f410 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2f420 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2f430 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2f440 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2f450 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2f460 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2f470 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2f480 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2f490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2f4a0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2f4b0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2f4c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2f4d0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2f4e0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2f4f0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2f500 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2f510 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2f520 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2f530 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2f540 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2f550 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2f560 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2f570 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2f580 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2f590 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2f5a0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2f5b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2f5c0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2f5d0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2f5e0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2f5f0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2f600 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2f610 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2f620 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2f630 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2f640 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2f650 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2f660 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2f670 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2f680 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2f690 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2f6a0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2f6b0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2f6c0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2f6d0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2f6e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2f6f0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2f700 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2f710 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2f720 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2f730 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2f740 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2f750 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2f760 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2f770 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2f780 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
2f790 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2f7a0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
2f7b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f7c0 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
2f7d0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2f7e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2f7f0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
2f800 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2f810 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
2f820 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
2f830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2f840 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
2f850 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f860 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2f870 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
2f880 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2f890 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2f8a0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
2f8b0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2f8c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2f8d0 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
2f8e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2f8f0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2f900 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2f910 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2f920 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2f930 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2f940 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2f950 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2f960 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
2f970 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2f980 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2f990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f9a0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
2f9b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f9c0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
2f9d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f9e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2f9f0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
2fa00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
2fa10 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
2fa20 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2fa30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fa40 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
2fa50 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
2fa60 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
2fa70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2fa80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
2fa90 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
2faa0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
2fab0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
2fac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fad0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
2fae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2faf0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2fb00 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2fb10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2fb20 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2fb30 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2fb40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2fb50 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2fb60 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2fb70 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2fb80 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2fb90 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2fba0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2fbb0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2fbc0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2fbd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2fbe0 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
2fbf0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2fc00 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
2fc10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2fc20 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2fc30 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2fc40 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2fc50 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2fc60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fc70 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2fc80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2fc90 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2fca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2fcb0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2fcc0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2fcd0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2fce0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
2fcf0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2fd00 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2fd10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2fd20 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2fd30 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2fd40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fd50 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2fd60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2fd70 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
2fd80 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2fd90 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2fda0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fdb0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2fdc0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2fdd0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
2fde0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
2fdf0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2fe00 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2fe10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2fe20 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
2fe30 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2fe40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fe50 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2fe60 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
2fe70 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
2fe80 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
2fe90 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
2fea0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
2feb0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
2fec0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2fed0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
2fee0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2fef0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2ff00 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2ff10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2ff20 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
2ff30 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
2ff40 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
2ff50 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
2ff60 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
2ff70 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2ff80 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
2ff90 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2ffa0 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
2ffb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ffc0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2ffd0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2ffe0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
2fff0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
30000 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
30010 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
30020 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
30030 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
30040 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
30050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30060 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
30070 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
30080 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
30090 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
300a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
300b0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
300c0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
300d0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
300e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
300f0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
30100 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
30110 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
30120 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
30130 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
30140 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
30150 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
30160 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
30170 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
30180 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
30190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
301a0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
301b0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
301c0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
301d0 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
301e0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
301f0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
30200 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
30210 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
30220 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
30230 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
30240 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
30250 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
30260 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
30270 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
30280 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
30290 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
302a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
302b0 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
302c0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
302d0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
302e0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
302f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
30300 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
30310 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
30320 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
30330 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
30340 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
30350 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
30360 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
30370 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
30380 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
30390 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
303a0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
303b0 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
303c0 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
303d0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
303e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
303f0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
30400 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
30410 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
30420 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
30430 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
30440 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
30450 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
30460 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
30470 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
30480 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30490 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
304a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
304b0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
304c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
304d0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
304e0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
304f0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
30500 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30510 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
30520 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
30530 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
30540 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
30550 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
30560 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
30570 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30580 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
30590 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
305a0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
305b0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
305c0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
305d0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
305e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
305f0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
30600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30610 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
30620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30630 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
30640 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
30650 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
30660 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
30670 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
30680 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
30690 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
306a0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
306b0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
306c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
306d0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
306e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
306f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
30700 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
30710 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
30720 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
30730 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
30740 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
30750 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
30760 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
30770 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
30780 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
30790 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
307a0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
307b0 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
307c0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
307d0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
307e0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
307f0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
30800 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
30810 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
30820 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
30830 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
30840 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
30850 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
30860 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
30870 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
30880 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
30890 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
308a0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
308b0 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
308c0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
308d0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
308e0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
308f0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
30900 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
30910 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
30920 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
30930 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
30940 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
30950 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
30960 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
30970 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
30980 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
30990 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
309a0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
309b0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
309c0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
309d0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
309e0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
309f0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
30a00 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
30a10 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
30a20 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
30a30 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
30a40 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
30a50 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
30a60 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
30a70 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
30a80 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
30a90 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
30aa0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
30ab0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
30ac0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
30ad0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
30ae0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
30af0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
30b00 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
30b10 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
30b20 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
30b30 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
30b40 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
30b50 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
30b60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30b70 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
30b80 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
30b90 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
30ba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30bb0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
30bc0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
30bd0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
30be0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
30bf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30c00 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
30c10 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
30c20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
30c30 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
30c40 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
30c50 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
30c60 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
30c70 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
30c80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30c90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
30ca0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
30cb0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
30cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
30cd0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
30ce0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
30cf0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
30d00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30d10 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
30d20 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
30d30 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
30d40 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
30d50 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
30d60 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
30d70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30d80 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
30d90 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
30da0 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
30db0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
30dc0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30dd0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
30de0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
30df0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
30e00 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
30e10 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
30e20 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
30e30 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
30e40 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
30e50 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
30e60 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
30e70 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
30e80 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
30e90 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
30ea0 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
30eb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
30ec0 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
30ed0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
30ee0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
30ef0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
30f00 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
30f10 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
30f20 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
30f30 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
30f40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30f50 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
30f60 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
30f70 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
30f80 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
30f90 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
30fa0 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
30fb0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
30fc0 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
30fd0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
30fe0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
30ff0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
31000 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
31010 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
31020 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
31030 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
31040 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
31050 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
31060 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
31070 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
31080 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
31090 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
310a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
310b0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
310c0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
310d0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
310e0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
310f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31100 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
31110 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
31120 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
31130 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
31140 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
31150 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
31160 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
31170 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
31180 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
31190 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
311a0 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
311b0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
311c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
311d0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
311e0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
311f0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
31200 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
31210 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
31220 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
31230 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
31240 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
31250 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
31260 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
31270 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
31280 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
31290 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
312a0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
312b0 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
312c0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
312d0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
312e0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
312f0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
31300 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
31310 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
31320 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
31330 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
31340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31350 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
31360 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
31370 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31380 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
31390 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
313a0 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
313b0 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
313c0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
313d0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
313e0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
313f0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
31400 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
31410 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
31420 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
31430 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
31440 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
31450 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
31460 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
31470 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
31480 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
31490 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
314a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
314b0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
314c0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
314d0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
314e0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
314f0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
31500 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31510 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
31520 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
31530 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
31540 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
31550 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
31560 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
31570 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
31580 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
31590 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
315a0 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
315b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
315c0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
315d0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
315e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
315f0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
31600 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
31610 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
31620 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
31630 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
31640 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
31650 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
31660 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
31670 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
31680 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
31690 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
316a0 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
316b0 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
316c0 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
316d0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
316e0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
316f0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
31700 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
31710 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
31720 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
31730 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
31740 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
31750 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
31760 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
31770 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
31780 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
31790 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
317a0 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
317b0 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
317c0 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
317d0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
317e0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
317f0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
31800 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
31810 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
31820 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
31830 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
31840 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
31850 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
31860 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
31870 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
31880 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
31890 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
318a0 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
318b0 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
318c0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
318d0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
318e0 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
318f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31900 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
31910 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
31920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
31930 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
31940 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
31950 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31960 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
31970 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
31980 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
31990 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
319a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
319b0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
319c0 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
319d0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
319e0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
319f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
31a00 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
31a10 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
31a20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
31a30 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
31a40 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
31a50 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
31a60 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
31a70 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
31a80 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
31a90 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
31aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
31ab0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
31ac0 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
31ad0 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
31ae0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
31af0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
31b00 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
31b10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
31b20 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
31b30 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
31b40 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31b50 6e 20 69 73 20 73 70 65 63 69 66 65 64 20 75 73  n is specifed us
31b60 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  ing.**      [sql
31b70 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
31b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
31b90 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69  HE],...)..** <li
31ba0 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65  > The page cache
31bb0 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20   allocates from 
31bc0 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70  its own memory p
31bd0 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ool supplied.** 
31be0 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
31bf0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
31c00 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
31c10 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74  E],...) rather t
31c20 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d  han.**      from
31c30 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f   the heap..** </
31c40 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69  ul>)^.**.** Begi
31c50 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
31c60 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c  e version 3.7.3,
31c70 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
31c80 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
31c90 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
31ca0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
31cb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
31cc0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
31cd0 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  EMENT].** compil
31ce0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
31cf0 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20   invoked.  With 
31d00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
31d10 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
31d20 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  ],.** the soft h
31d30 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
31d40 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d  orced on every m
31d50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31d60 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53  .  Without.** [S
31d70 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
31d80 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
31d90 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
31da0 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66  imit is only enf
31db0 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65  orced.** when me
31dc0 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
31dd0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61  d by the page ca
31de0 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75  che.  Testing su
31df0 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61  ggests that beca
31e00 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20  use.** the page 
31e10 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65  cache is the pre
31e20 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20  dominate memory 
31e30 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20  user in SQLite, 
31e40 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
31e50 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76  ions will achiev
31e60 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20  e adequate soft 
31e70 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72  heap limit enfor
31e80 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a  cement without.*
31e90 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51  * the use of [SQ
31ea0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
31eb0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
31ec0 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d  **.** The circum
31ed0 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68  stances under wh
31ee0 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ich SQLite will 
31ef0 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74  enforce the soft
31f00 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a   heap limit may.
31f10 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75  ** changes in fu
31f20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
31f30 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69   SQLite..*/.sqli
31f40 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
31f50 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
31f60 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64(sqlite3_int6
31f70 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  4 N);../*.** CAP
31f80 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
31f90 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69  d Soft Heap Limi
31fa0 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44  t Interface.** D
31fb0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
31fc0 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63  This is a deprec
31fd0 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  ated version of 
31fe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  the [sqlite3_sof
31ff0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
32000 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  ].** interface. 
32010 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
32020 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69   provided for hi
32030 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
32040 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20  bility.** only. 
32050 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61   All new applica
32060 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65  tions should use
32070 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
32080 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
32090 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  64()] interface 
320a0 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73  rather than this
320b0 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   one..*/.SQLITE_
320c0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
320d0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
320e0 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a  p_limit(int N);.
320f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32100 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
32110 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
32120 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
32130 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
32140 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
32150 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
32160 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
32170 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
32180 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
32190 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
321a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
321b0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
321c0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
321d0 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
321e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
321f0 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
32200 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
32210 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
32220 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
32230 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
32240 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e  tion. ^The secon
32250 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
32260 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
32270 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
32280 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
32290 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74  "temp", or an at
322a0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
322b0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
322c0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
322d0 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20  le or NULL. ^If 
322e0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
322f0 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
32300 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
32310 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
32320 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
32330 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  same algorithm u
32340 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  sed by the datab
32350 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a  ase engine to.**
32360 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
32370 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
32380 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ences..**.** ^Th
32390 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
323a0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
323b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
323c0 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
323d0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
323e0 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
323f0 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
32400 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
32410 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
32420 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
32430 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
32440 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
32450 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
32460 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
32470 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
32480 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
32490 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
324a0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
324b0 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
324c0 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
324d0 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
324e0 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
324f0 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
32500 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
32510 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
32520 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
32530 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
32540 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
32550 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
32560 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
32570 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
32580 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
32590 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
325a0 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
325b0 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
325c0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
325d0 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
325e0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
325f0 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
32600 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
32610 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
32620 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
32630 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
32640 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
32650 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
32660 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
32670 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
32680 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
32690 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
326a0 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
326b0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
326c0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
326d0 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
326e0 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
326f0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
32700 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
32710 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
32720 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
32730 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
32740 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
32750 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
32760 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
32770 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
32780 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
32790 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
327a0 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
327b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
327c0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
327d0 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
327e0 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
327f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
32800 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
32810 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
32820 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
32830 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
32840 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
32850 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
32860 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
32870 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
32880 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
32890 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
328a0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
328b0 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
328c0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
328d0 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
328e0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
328f0 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
32900 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
32910 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
32920 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
32930 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
32940 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
32950 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
32960 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
32970 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
32980 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
32990 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
329a0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
329b0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
329c0 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
329d0 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
329e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
329f0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
32a00 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
32a10 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
32a20 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
32a30 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
32a40 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
32a50 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
32a60 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
32a70 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
32a80 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
32a90 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
32aa0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
32ab0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
32ac0 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
32ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32ae0 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
32af0 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
32b00 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
32b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
32b20 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
32b30 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
32b40 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
32b50 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
32b60 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
32b70 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
32b80 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
32b90 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
32ba0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
32bb0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
32bc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
32bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32be0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
32bf0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
32c00 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
32c10 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
32c20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
32c30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
32c40 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
32c50 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
32c60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
32c70 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
32c80 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
32c90 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
32ca0 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
32cb0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
32cc0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
32cd0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
32ce0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
32cf0 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
32d00 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
32d10 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
32d20 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
32d30 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
32d40 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
32d50 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
32d60 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
32d70 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
32d80 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
32d90 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
32da0 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
32db0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
32dc0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
32dd0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
32de0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
32df0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
32e00 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
32e10 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
32e20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
32e30 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
32e40 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
32e50 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
32e60 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   file..**.** ^Th
32e70 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
32e80 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
32e90 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
32ea0 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69   load an.** SQLi
32eb0 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
32ec0 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
32ed0 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
32ee0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74  ..**.** ^The ent
32ef0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
32f00 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79  c..** ^zProc may
32f10 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
32f20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
32f30 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
32f40 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20  .** defaults to 
32f50 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
32f60 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68  on_init"..** ^Th
32f70 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
32f80 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
32f90 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
32fa0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
32fb0 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
32fc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
32fd0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
32fe0 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  g..** ^If an err
32ff0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
33000 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
33010 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71   then the.** [sq
33020 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
33030 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
33040 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
33050 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72  to.** fill *pzEr
33060 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
33070 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
33080 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
33090 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
330a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
330b0 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ]. The calling f
330c0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  unction.** shoul
330d0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
330e0 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
330f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
33100 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
33110 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
33120 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
33130 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  * [sqlite3_enabl
33140 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
33150 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  ()] prior to cal
33160 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a  ling this API,.*
33170 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  * otherwise an e
33180 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
33190 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
331a0 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f   also the [load_
331b0 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20  extension() SQL 
331c0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e  function]..*/.in
331d0 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
331e0 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
331f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33200 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
33210 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
33220 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
33230 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
33240 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
33250 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
33260 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
33270 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
33280 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
33290 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
332a0 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
332b0 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
332c0 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
332d0 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
332e0 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
332f0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
33300 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
33310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
33320 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
33330 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
33340 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f  .**.** ^So as no
33350 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
33360 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
33370 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
33380 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
33390 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
333a0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
333b0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
333c0 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
333d0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
333e0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
333f0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
33400 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
33410 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
33420 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
33430 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
33440 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
33450 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
33460 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45  nd off..**.** ^E
33470 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
33480 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
33490 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23  lt. See ticket #
334a0 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74  1863..** ^Call t
334b0 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  he sqlite3_enabl
334c0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
334d0 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  () routine with 
334e0 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74  onoff==1.** to t
334f0 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
33500 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
33510 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
33520 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74  =0 to turn.** it
33530 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
33540 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33550 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
33560 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
33570 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
33580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33590 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
335a0 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69  ad Statically Li
335b0 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a  nked Extensions.
335c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
335d0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
335e0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66   xEntryPoint() f
335f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
33600 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63  voked for.** eac
33610 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
33620 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
33630 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
33640 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20 74  e idea here is t
33650 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69  hat.** xEntryPoi
33660 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 72  nt() is the entr
33670 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74  y point for a st
33680 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
33690 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
336a0 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62  .** that is to b
336b0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
336c0 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20  loaded into all 
336d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
336e0 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
336f0 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68  ^(Even though th
33700 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f  e function proto
33710 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 20  type shows that 
33720 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61  xEntryPoint() ta
33730 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65  kes.** no argume
33740 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20  nts and returns 
33750 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76  void, SQLite inv
33760 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74  okes xEntryPoint
33770 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a  () with three.**
33780 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65   arguments and e
33790 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67  xpects and integ
337a0 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 20  er result as if 
337b0 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66  the signature of
337c0 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f   the.** entry po
337d0 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c  int where as fol
337e0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
337f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
33800 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e   &nbsp;  int xEn
33810 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62  tryPoint(.** &nb
33820 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a  sp;    sqlite3 *
33830 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  db,.** &nbsp;   
33840 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
33850 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70  ErrMsg,.** &nbsp
33860 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63  ;    const struc
33870 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
33880 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a  utines *pThunk.*
33890 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20  * &nbsp;  );.** 
338a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
338b0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  te>)^.**.** If t
338c0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72  he xEntryPoint r
338d0 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72  outine encounter
338e0 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73  s an error, it s
338f0 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72  hould make *pzEr
33900 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  rMsg.** point to
33910 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
33920 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f  error message (o
33930 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
33940 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
33950 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20  ).** and return 
33960 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
33970 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53  error code].  ^S
33980 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 68  QLite ensures th
33990 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20  at *pzErrMsg.** 
339a0 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63  is NULL before c
339b0 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72  alling the xEntr
339c0 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69  yPoint().  ^SQLi
339d0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  te will invoke.*
339e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
339f0 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20  )] on *pzErrMsg 
33a00 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e  after xEntryPoin
33a10 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49  t() returns.  ^I
33a20 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50  f any.** xEntryP
33a30 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61  oint() returns a
33a40 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71  n error, the [sq
33a50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
33a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
33a70 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
33a80 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c  3_open_v2()] cal
33a90 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  l that provoked 
33aa0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  the xEntryPoint(
33ab0 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a  ) will fail..**.
33ac0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
33ad0 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
33ae0 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e  on(X) with an en
33af0 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74  try point X that
33b00 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f   is already.** o
33b10 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75  n the list of au
33b20 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
33b30 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  ns is a harmless
33b40 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72   no-op. ^No entr
33b50 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20  y point.** will 
33b60 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74  be called more t
33b70 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  han once for eac
33b80 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
33b90 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70  ction that is op
33ba0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ened..**.** See 
33bb0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72  also: [sqlite3_r
33bc0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
33bd0 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ion()]..*/.int s
33be0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
33bf0 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e  nsion(void (*xEn
33c00 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29  tryPoint)(void))
33c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33c20 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
33c30 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
33c40 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ding.**.** ^This
33c50 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 62   interface disab
33c60 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69  les all automati
33c70 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65  c extensions pre
33c80 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73  viously.** regis
33c90 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
33ca0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
33cb0 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  ion()]..*/.void 
33cc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
33cd0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
33ce0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  d);../*.** The i
33cf0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
33d00 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33d10 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
33d20 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
33d30 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
33d40 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
33d50 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
33d60 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
33d70 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
33d80 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
33d90 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
33da0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
33db0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
33dc0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
33dd0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33de0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
33df0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
33e00 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
33e10 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
33e20 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
33e30 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
33e40 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
33e50 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
33e60 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
33e70 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
33e80 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
33e90 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33ea0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
33eb0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
33ec0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
33ed0 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
33ee0 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
33ef0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33f00 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
33f10 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
33f20 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
33f30 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
33f40 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
33f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33f60 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
33f70 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
33f80 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
33f90 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
33fa0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54   module}.**.** T
33fb0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
33fc0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
33fd0 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  a a "virtual tab
33fe0 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
33ff0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
34000 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
34010 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
34020 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
34030 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
34040 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
34050 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
34060 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61  .**.** ^A virtua
34070 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
34080 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
34090 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
340a0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
340b0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
340c0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
340d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
340e0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
340f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34100 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
34110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
34120 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54  ule_v2()]..** ^T
34130 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
34140 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
34150 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
34160 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
34170 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
34180 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
34190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
341a0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
341b0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
341c0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
341d0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
341e0 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
341f0 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
34200 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
34210 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
34220 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
34230 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
34240 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
34250 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
34260 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
34270 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
34280 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
34290 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
342a0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
342b0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
342c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
342d0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
342e0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
342f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
34300 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
34310 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
34320 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
34330 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
34340 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
34350 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
34360 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34370 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
34380 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
34390 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
343a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
343b0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
343c0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
343d0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
343e0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
343f0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
34400 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
34410 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
34420 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
34430 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
34440 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
34450 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
34460 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
34470 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
34480 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
34490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
344a0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
344b0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
344c0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
344d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
344e0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
344f0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
34500 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
34510 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
34520 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
34530 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
34540 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
34550 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
34560 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
34570 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
34580 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
34590 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
345a0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
345b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
345c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
345d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
345e0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
345f0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
34600 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
34610 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
34620 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
34630 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34640 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
34650 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
34660 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
34670 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
34680 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
34690 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
346a0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
346b0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
346c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
346d0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
346e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
346f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
34700 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
34710 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
34720 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
34730 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
34740 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
34750 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
34760 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  w);.};../*.** CA
34770 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
34780 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49  Table Indexing I
34790 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45  nformation.** KE
347a0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
347b0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a  index_info.**.**
347c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
347d0 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
347e0 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
347f0 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
34800 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68  as part.** of th
34810 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
34820 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
34830 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
34840 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
34850 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
34860 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64  om the [xBestInd
34870 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  ex].** method of
34880 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
34890 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20  e module].  The 
348a0 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
348b0 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
348c0 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
348d0 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
348e0 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
348f0 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
34900 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
34910 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
34920 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
34930 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69   ^(The aConstrai
34940 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72  nt[] array recor
34950 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ds WHERE clause 
34960 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74  constraints of t
34970 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c  he form:.**.** <
34980 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d  blockquote>colum
34990 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b  n OP expr</block
349a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65  quote>.**.** whe
349b0 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
349c0 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
349d0 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68  r &gt;=.)^  ^(Th
349e0 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
349f0 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72  rator is.** stor
34a00 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ed in aConstrain
34a10 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65  t[].op using one
34a20 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   of the.** [SQLI
34a30 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
34a40 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f  INT_EQ | SQLITE_
34a50 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
34a60 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20  _ values].)^.** 
34a70 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74  ^(The index of t
34a80 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
34a90 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74  red in.** aConst
34aa0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
34ab0 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e  )^  ^(aConstrain
34ac0 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
34ad0 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
34ae0 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
34af0 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
34b00 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
34b10 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
34b20 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
34b30 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
34b40 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a   cannot.)^.**.**
34b50 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20   ^The optimizer 
34b60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
34b70 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
34b80 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
34b90 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
34ba0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
34bb0 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
34bc0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
34bd0 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
34be0 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
34bf0 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
34c00 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
34c10 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
34c20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68  possible..** ^Th
34c30 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
34c40 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
34c50 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
34c60 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a  terms that are.*
34c70 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68  * relevant to th
34c80 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72  e particular vir
34c90 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67  tual table being
34ca0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20   queried..**.** 
34cb0 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f  ^Information abo
34cc0 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
34cd0 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
34ce0 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
34cf0 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66  ** ^Each term of
34d00 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
34d10 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
34d20 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
34d30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42  e..**.** The [xB
34d40 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64  estIndex] method
34d50 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
34d60 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
34d70 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
34d80 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
34d90 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
34da0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66  to xFilter.  ^If
34db0 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
34dc0 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
34dd0 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
34de0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
34df0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
34e00 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
34e10 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
34e20 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
34e30 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43  n argv.  ^(If aC
34e40 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
34e50 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
34e60 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
34e70 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
34e80 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
34e90 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
34ea0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
34eb0 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
34ec0 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
34ed0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64  )^.**.** ^The id
34ee0 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20  xNum and idxPtr 
34ef0 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72  values are recor
34f00 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69  ded and passed i
34f10 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c  nto the.** [xFil
34f20 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20  ter] method..** 
34f30 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  ^[sqlite3_free()
34f40 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ] is used to fre
34f50 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20  e idxPtr if and 
34f60 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54  only if.** needT
34f70 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
34f80 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rue..**.** ^The 
34f90 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
34fa0 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75  means that outpu
34fb0 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d  t from [xFilter]
34fc0 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63  /[xNext] will oc
34fd0 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f  cur in.** the co
34fe0 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73  rrect order to s
34ff0 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52  atisfy the ORDER
35000 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68   BY clause so th
35010 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a  at no separate.*
35020 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69  * sorting step i
35030 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
35040 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64  * ^The estimated
35050 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e  Cost value is an
35060 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65   estimate of the
35070 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74   cost of doing t
35080 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72  he.** particular
35090 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c   lookup.  A full
350a0 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65   scan of a table
350b0 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20   with N entries 
350c0 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61  should have.** a
350d0 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62   cost of N.  A b
350e0 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20  inary search of 
350f0 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74  a table of N ent
35100 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
35110 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70   a.** cost of ap
35120 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28  proximately log(
35130 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  N)..*/.struct sq
35140 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
35150 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a   {.  /* Inputs *
35160 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61  /.  int nConstra
35170 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f  int;           /
35180 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72  * Number of entr
35190 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  ies in aConstrai
351a0 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  nt */.  struct s
351b0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
351c0 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69  straint {.     i
351d0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
351e0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
351f0 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20  mn on left-hand 
35200 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69  side of constrai
35210 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  nt */.     unsig
35220 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20  ned char op;    
35230 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69       /* Constrai
35240 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20  nt operator */. 
35250 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
35260 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a  r usable;     /*
35270 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f   True if this co
35280 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62  nstraint is usab
35290 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69  le */.     int i
352a0 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20  TermOffset;     
352b0 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74       /* Used int
352c0 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49  ernally - xBestI
352d0 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f  ndex should igno
352e0 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  re */.  } *aCons
352f0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
35300 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57     /* Table of W
35310 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
35320 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74  traints */.  int
35330 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
35340 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
35350 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68  r of terms in th
35360 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
35370 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  e */.  struct sq
35380 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
35390 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  rby {.     int i
353a0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
353b0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e       /* Column n
353c0 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e  umber */.     un
353d0 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
353e0 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
353f0 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65  for DESC.  False
35400 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d   for ASC. */.  }
35410 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20   *aOrderBy;     
35420 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65            /* The
35430 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35440 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73   */.  /* Outputs
35450 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
35460 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
35470 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
35480 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b    int argvIndex;
35490 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66             /* if
354a0 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20   >0, constraint 
354b0 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20  is part of argv 
354c0 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20  to xFilter */.  
354d0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
354e0 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f  omit;      /* Do
354f0 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74   not code a test
35500 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72   for this constr
35510 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  aint */.  } *aCo
35520 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20  nstraintUsage;. 
35530 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
35540 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
35550 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
35560 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
35570 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53   */.  char *idxS
35580 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
35590 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
355a0 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
355b0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
355c0 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54  c */.  int needT
355d0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20  oFreeIdxStr;    
355e0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72    /* Free idxStr
355f0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
35600 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f  ree() if true */
35610 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f  .  int orderByCo
35620 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a  nsumed;       /*
35630 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20   True if output 
35640 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72  is already order
35650 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65  ed */.  double e
35660 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
35670 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
35680 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
35690 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a  is index */.};..
356a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
356b0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f  Virtual Table Co
356c0 6e 73 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f  nstraint Operato
356d0 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  r Codes.**.** Th
356e0 65 73 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e  ese macros defin
356f0 65 64 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76  ed the allowed v
35700 61 6c 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  alues for the.**
35710 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f   [sqlite3_index_
35720 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e  info].aConstrain
35730 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45  t[].op field.  E
35740 61 63 68 20 76 61 6c 75 65 20 72 65 70 72 65 73  ach value repres
35750 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61  ents.** an opera
35760 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 72 74  tor that is part
35770 20 6f 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   of a constraint
35780 20 74 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45   term in the wHE
35790 52 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20  RE clause of.** 
357a0 61 20 71 75 65 72 79 20 74 68 61 74 20 75 73 65  a query that use
357b0 73 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  s a [virtual tab
357c0 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  le]..*/.#define 
357d0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
357e0 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a  STRAINT_EQ    2.
357f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
35800 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
35810 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  GT    4.#define 
35820 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
35830 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a  STRAINT_LE    8.
35840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
35850 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
35860 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65  LT    16.#define
35870 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
35880 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33  NSTRAINT_GE    3
35890 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
358a0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
358b0 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a  T_MATCH 64../*.*
358c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
358d0 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54  ster A Virtual T
358e0 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74  able Implementat
358f0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
35900 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
35910 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
35920 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
35930 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65  ble module] name
35940 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d  ..** ^Module nam
35950 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73  es must be regis
35960 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20  tered before.** 
35970 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b  creating a new [
35980 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75  virtual table] u
35990 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20  sing the module 
359a0 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67  and before using
359b0 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e   a.** preexistin
359c0 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  g [virtual table
359d0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  ] for the module
359e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64  ..**.** ^The mod
359f0 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69  ule name is regi
35a00 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64  stered on the [d
35a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a20 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  on] specified.**
35a30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
35a40 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e  rameter.  ^The n
35a50 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
35a60 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
35a70 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  e .** second par
35a80 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68  ameter.  ^The th
35a90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
35aa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
35ab0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
35ac0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74  ion of the [virt
35ad0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
35ae0 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68  ].   ^The fourth
35af0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
35b00 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c   an arbitrary cl
35b10 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65  ient data pointe
35b20 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
35b30 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f   through.** into
35b40 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61   the [xCreate] a
35b50 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
35b60 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72  thods of the vir
35b70 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
35b80 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20  e.** when a new 
35b90 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
35ba0 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65   be being create
35bb0 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a  d or reinitializ
35bc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
35bd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
35be0 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66  dule_v2() interf
35bf0 61 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20  ace has a fifth 
35c00 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
35c10 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
35c20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  to a destructor 
35c30 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44  for the pClientD
35c40 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ata.  ^SQLite wi
35c50 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  ll.** invoke the
35c60 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
35c70 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e  tion (if it is n
35c80 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51  ot NULL) when SQ
35c90 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65  Lite.** no longe
35ca0 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69  r needs the pCli
35cb0 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e  entData pointer.
35cc0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
35cd0 72 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62  r will also.** b
35ce0 65 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  e invoked if the
35cf0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35d00 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
35d10 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54  2() fails..** ^T
35d20 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
35d30 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
35d40 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
35d50 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
35d60 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
35d70 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
35d80 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
35d90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
35da0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
35db0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
35dc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
35dd0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
35de0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
35df0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
35e00 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
35e10 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
35e20 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
35e30 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
35e40 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
35e50 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
35e60 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
35e70 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
35e80 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
35e90 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
35ea0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
35eb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
35ec0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
35ed0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35ee0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
35ef0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
35f00 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
35f10 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
35f20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
35f30 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
35f40 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
35f50 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
35f60 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
35f70 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
35f80 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
35f90 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
35fa0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
35fb0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
35fc0 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
35fd0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
35fe0 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
35ff0 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
36000 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
36010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36020 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
36030 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
36040 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
36050 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
36060 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
36070 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
36080 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
36090 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
360a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
360b0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
360c0 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
360d0 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
360e0 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
360f0 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
36100 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
36110 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
36120 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
36130 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36140 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
36150 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
36160 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
36170 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
36180 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
36190 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
361a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
361b0 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
361c0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
361d0 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
361e0 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
361f0 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
36200 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
36210 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
36220 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
36230 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
36240 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
36250 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
36260 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
36270 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
36280 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
36290 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
362a0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
362b0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
362c0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
362d0 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
362e0 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
362f0 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
36300 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
36310 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
36320 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
36330 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
36340 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
36350 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
36360 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
36370 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
36380 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
36390 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
363a0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
363b0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
363c0 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
363d0 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
363e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
363f0 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
36400 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
36410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36420 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
36430 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
36440 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
36450 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
36460 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36470 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
36480 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
36490 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
364a0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
364b0 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
364c0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
364d0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
364e0 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
364f0 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
36500 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
36510 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
36520 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
36530 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
36540 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
36550 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
36560 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
36570 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
36580 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
36590 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
365a0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
365b0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
365c0 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
365d0 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
365e0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
365f0 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
36600 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
36610 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
36620 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
36630 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
36640 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
36650 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
36660 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
36670 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
36680 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
36690 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
366a0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
366b0 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
366c0 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
366d0 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
366e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
366f0 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
36700 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
36710 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
36720 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
36730 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
36740 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
36750 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
36760 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
36770 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
36780 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
36790 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
367a0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
367b0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
367c0 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
367d0 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
367e0 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
367f0 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
36800 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
36810 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
36820 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
36830 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
36840 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
36850 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
36860 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
36870 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
36880 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
36890 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
368a0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
368b0 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
368c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
368d0 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
368e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
368f0 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
36900 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
36910 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
36920 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
36930 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
36940 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
36950 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
36960 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
36970 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
36980 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
36990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
369a0 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
369b0 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
369c0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
369d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
369e0 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
369f0 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
36a00 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
36a10 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
36a20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
36a30 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
36a40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
36a50 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
36a60 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
36a70 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
36a80 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
36a90 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
36aa0 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
36ab0 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
36ac0 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
36ad0 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
36ae0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
36af0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
36b00 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
36b10 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
36b20 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
36b30 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
36b40 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
36b50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
36b60 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
36b70 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
36b80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
36b90 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
36ba0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
36bb0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
36bc0 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
36bd0 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
36be0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
36bf0 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
36c00 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
36c10 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
36c20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
36c30 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
36c40 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
36c50 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
36c60 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
36c70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
36c80 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
36c90 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
36ca0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
36cb0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
36cc0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
36cd0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
36ce0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
36cf0 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
36d00 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
36d10 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
36d20 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
36d30 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
36d40 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
36d50 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
36d60 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
36d70 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
36d80 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
36d90 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
36da0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
36db0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
36dc0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
36dd0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
36de0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
36df0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
36e00 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
36e10 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
36e20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
36e30 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
36e40 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
36e50 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
36e60 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
36e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36e80 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
36e90 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
36ea0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
36eb0 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
36ec0 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
36ed0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
36ee0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
36ef0 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
36f00 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
36f10 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
36f20 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
36f30 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
36f40 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
36f50 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
36f60 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
36f70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
36f80 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
36f90 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
36fa0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
36fb0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
36fc0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
36fd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
36fe0 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
36ff0 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
37000 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
37010 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
37020 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
37030 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
37040 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
37050 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
37060 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
37070 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
37080 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
37090 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
370a0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
370b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
370c0 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
370d0 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
370e0 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
370f0 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
37100 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
37110 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
37120 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
37130 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
37140 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
37150 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
37160 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
37170 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
37180 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
37190 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
371a0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
371b0 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
371c0 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
371d0 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
371e0 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
371f0 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
37200 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
37210 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
37220 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
37230 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
37240 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
37250 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
37260 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
37270 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
37280 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
37290 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
372a0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
372b0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
372c0 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
372d0 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
372e0 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
372f0 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
37300 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
37310 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
37320 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
37330 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
37340 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
37350 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
37360 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
37370 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
37380 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
37390 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
373a0 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
373b0 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
373c0 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
373d0 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
373e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
373f0 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
37400 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
37410 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
37420 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
37430 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
37440 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
37450 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
37460 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
37470 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
37480 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
37490 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
374a0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
374b0 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
374c0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
374d0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
374e0 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
374f0 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
37500 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
37510 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
37520 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
37530 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
37540 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
37550 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
37560 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
37570 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
37580 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37590 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
375a0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
375b0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
375c0 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
375d0 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
375e0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
375f0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
37600 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
37610 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
37620 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
37630 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
37640 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
37650 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
37660 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
37670 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
37680 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
37690 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
376a0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
376b0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
376c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
376d0 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
376e0 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
376f0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
37700 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
37710 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
37720 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
37730 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
37740 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
37750 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
37760 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
37770 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
37780 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
37790 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
377a0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
377b0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
377c0 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
377d0 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
377e0 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
377f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
37800 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
37810 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
37820 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
37830 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
37840 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
37850 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
37860 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
37870 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
37880 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
37890 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
378a0 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
378b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
378c0 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
378d0 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
378e0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
378f0 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
37900 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
37910 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
37920 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
37930 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
37940 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
37950 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
37960 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
37970 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
37980 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
37990 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
379a0 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
379b0 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
379c0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
379d0 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
379e0 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
379f0 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
37a00 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
37a10 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
37a20 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
37a30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
37a40 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
37a50 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
37a60 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
37a70 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
37a80 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
37a90 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
37aa0 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
37ab0 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
37ac0 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
37ad0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
37ae0 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
37af0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
37b00 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
37b10 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
37b20 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
37b30 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
37b40 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
37b50 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
37b60 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
37b70 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
37b80 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
37b90 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
37ba0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
37bb0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
37bc0 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
37bd0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
37be0 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
37bf0 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
37c00 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
37c10 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
37c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
37c30 6f 76 65 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c  ove a BLOB Handl
37c40 65 20 74 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a  e to a New Row.*
37c50 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
37c60 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ion is used to m
37c70 6f 76 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20  ove an existing 
37c80 62 6c 6f 62 20 68 61 6e 64 6c 65 20 73 6f 20 74  blob handle so t
37c90 68 61 74 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a  hat it points.**
37ca0 20 74 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20   to a different 
37cb0 72 6f 77 20 6f 66 20 74 68 65 20 73 61 6d 65 20  row of the same 
37cc0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
37cd0 5e 54 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20  ^The new row is 
37ce0 69 64 65 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79  identified.** by
37cf0 20 74 68 65 20 72 6f 77 69 64 20 76 61 6c 75 65   the rowid value
37d00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
37d10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20  econd argument. 
37d20 4f 6e 6c 79 20 74 68 65 20 72 6f 77 20 63 61 6e  Only the row can
37d30 20 62 65 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20   be.** changed. 
37d40 5e 54 68 65 20 64 61 74 61 62 61 73 65 2c 20 74  ^The database, t
37d50 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
37d60 6f 6e 20 77 68 69 63 68 20 74 68 65 20 62 6c 6f  on which the blo
37d70 62 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e  b handle is open
37d80 0a 2a 2a 20 72 65 6d 61 69 6e 20 74 68 65 20 73  .** remain the s
37d90 61 6d 65 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65  ame. Moving an e
37da0 78 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e  xisting blob han
37db0 64 6c 65 20 74 6f 20 61 20 6e 65 77 20 72 6f 77  dle to a new row
37dc0 20 63 61 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65   can be.** faste
37dd0 72 20 74 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74  r than closing t
37de0 68 65 20 65 78 69 73 74 69 6e 67 20 68 61 6e 64  he existing hand
37df0 6c 65 20 61 6e 64 20 6f 70 65 6e 69 6e 67 20 61  le and opening a
37e00 20 6e 65 77 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20   new one..**.** 
37e10 5e 28 54 68 65 20 6e 65 77 20 72 6f 77 20 6d 75  ^(The new row mu
37e20 73 74 20 6d 65 65 74 20 74 68 65 20 73 61 6d 65  st meet the same
37e30 20 63 72 69 74 65 72 69 61 20 61 73 20 66 6f 72   criteria as for
37e40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
37e50 70 65 6e 28 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d  pen()] -.** it m
37e60 75 73 74 20 65 78 69 73 74 20 61 6e 64 20 74 68  ust exist and th
37e70 65 72 65 20 6d 75 73 74 20 62 65 20 65 69 74 68  ere must be eith
37e80 65 72 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78  er a blob or tex
37e90 74 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20 69  t value stored i
37ea0 6e 0a 2a 2a 20 74 68 65 20 6e 6f 6d 69 6e 61 74  n.** the nominat
37eb0 65 64 20 63 6f 6c 75 6d 6e 2e 29 5e 20 5e 49 66  ed column.)^ ^If
37ec0 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20   the new row is 
37ed0 6e 6f 74 20 70 72 65 73 65 6e 74 20 69 6e 20 74  not present in t
37ee0 68 65 20 74 61 62 6c 65 2c 20 6f 72 20 69 66 0a  he table, or if.
37ef0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 63  ** it does not c
37f00 6f 6e 74 61 69 6e 20 61 20 62 6c 6f 62 20 6f 72  ontain a blob or
37f10 20 74 65 78 74 20 76 61 6c 75 65 2c 20 6f 72 20   text value, or 
37f20 69 66 20 61 6e 6f 74 68 65 72 20 65 72 72 6f 72  if another error
37f30 20 6f 63 63 75 72 73 2c 20 61 6e 0a 2a 2a 20 53   occurs, an.** S
37f40 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65  QLite error code
37f50 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
37f60 20 74 68 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65   the blob handle
37f70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 61   is considered a
37f80 62 6f 72 74 65 64 2e 0a 2a 2a 20 5e 41 6c 6c 20  borted..** ^All 
37f90 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
37fa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
37fb0 62 5f 72 65 61 64 28 29 5d 2c 20 5b 73 71 6c 69  b_read()], [sqli
37fc0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
37fd0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
37fe0 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 29 5d 20  _blob_reopen()] 
37ff0 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64 20 62 6c  on an aborted bl
38000 6f 62 20 68 61 6e 64 6c 65 20 69 6d 6d 65 64 69  ob handle immedi
38010 61 74 65 6c 79 20 72 65 74 75 72 6e 0a 2a 2a 20  ately return.** 
38020 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 20 5e 43  SQLITE_ABORT. ^C
38030 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
38040 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 6f 6e  blob_bytes()] on
38050 20 61 6e 20 61 62 6f 72 74 65 64 20 62 6c 6f 62   an aborted blob
38060 20 68 61 6e 64 6c 65 0a 2a 2a 20 61 6c 77 61 79   handle.** alway
38070 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  s returns zero..
38080 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
38090 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61  tion sets the da
380a0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 65 72  tabase handle er
380b0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
380c0 73 61 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sage..*/.SQLITE_
380d0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
380e0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
380f0 6f 70 65 6e 28 73 71 6c 69 74 65 33 5f 62 6c 6f  open(sqlite3_blo
38100 62 20 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  b *, sqlite3_int
38110 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
38120 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c  3REF: Close A BL
38130 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  OB Handle.**.** 
38140 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20  ^Closes an open 
38150 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a  [BLOB handle]..*
38160 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20  *.** ^Closing a 
38170 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65  BLOB shall cause
38180 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61   the current tra
38190 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d  nsaction to comm
381a0 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61  it.** if there a
381b0 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42  re no other BLOB
381c0 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72  s, no pending pr
381d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
381e0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61  s, and the.** da
381f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38200 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d  n is in [autocom
38210 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49  mit mode]..** ^I
38220 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72  f any writes wer
38230 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c  e made to the BL
38240 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62  OB, they might b
38250 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a  e held in cache.
38260 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f  ** until the clo
38270 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20  se operation if 
38280 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a  they will fit..*
38290 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74  *.** ^(Closing t
382a0 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f  he BLOB often fo
382b0 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73  rces the changes
382c0 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20  .** out to disk 
382d0 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f  and so if any I/
382e0 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20  O errors occur, 
382f0 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  they will likely
38300 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65   occur.** at the
38310 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42   time when the B
38320 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  LOB is closed.  
38330 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20  Any errors that 
38340 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20  occur during.** 
38350 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f  closing are repo
38360 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65  rted as a non-ze
38370 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e  ro return value.
38380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42  )^.**.** ^(The B
38390 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e  LOB is closed un
383a0 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20  conditionally.  
383b0 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75  Even if this rou
383c0 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  tine returns.** 
383d0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74  an error code, t
383e0 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c  he BLOB is still
383f0 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   closed.)^.**.**
38400 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
38410 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75  outine with a nu
38420 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68  ll pointer (such
38430 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74   as would be ret
38440 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61  urned.** by a fa
38450 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  iled call to [sq
38460 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
38470 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73  )]) is a harmles
38480 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20  s no-op..*/.int 
38490 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
384a0 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  se(sqlite3_blob 
384b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
384c0 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20  REF: Return The 
384d0 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20  Size Of An Open 
384e0 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  BLOB.**.** ^Retu
384f0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20  rns the size in 
38500 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f  bytes of the BLO
38510 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  B accessible via
38520 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73   the .** success
38530 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c  fully opened [BL
38540 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74  OB handle] in it
38550 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  s only argument.
38560 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d    ^The.** increm
38570 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72  ental blob I/O r
38580 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79  outines can only
38590 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69   read or overwri
385a0 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a  ting existing.**
385b0 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74   blob content; t
385c0 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67  hey cannot chang
385d0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
385e0 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  blob..**.** This
385f0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
38600 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
38610 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
38620 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
38630 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
38640 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
38650 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
38660 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
38670 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
38680 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
38690 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
386a0 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
386b0 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
386c0 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
386d0 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
386e0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
386f0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
38700 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74  behavior..*/.int
38710 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79   sqlite3_blob_by
38720 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  tes(sqlite3_blob
38730 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
38740 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20  3REF: Read Data 
38750 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72  From A BLOB Incr
38760 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20  ementally.**.** 
38770 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
38780 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  is used to read 
38790 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65  data from an ope
387a0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
387b0 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  into a.** caller
387c0 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
387d0 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74  . N bytes of dat
387e0 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  a are copied int
387f0 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72  o buffer Z.** fr
38800 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  om the open BLOB
38810 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
38820 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a  fset iOffset.)^.
38830 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74  **.** ^If offset
38840 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
38850 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
38860 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
38870 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
38880 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
38890 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
388a0 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20  a is read.  ^If 
388b0 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a  N or iOffset is.
388c0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
388d0 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  o, [SQLITE_ERROR
388e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
388f0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
38900 64 2e 0a