/ Hex Artifact Content
Login

Artifact 660a7db4b052f0e390842fcaae49e3de5e10194d:


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 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  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 54 68 6f 73 65 20 62  ct..  ** Those b
a740: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
a750: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
a760: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
a770: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
a780: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a790: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a7a0: 2c 20 76 6f 69 64 20 2a 70 46 75 6e 63 29 3b 0a  , void *pFunc);.
a7b0: 20 20 76 6f 69 64 20 2a 28 2a 78 47 65 74 53 79    void *(*xGetSy
a7c0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
a7d0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a7e0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
a7f0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
a800: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
a810: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a820: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
a830: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
a840: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
a850: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
a860: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
a870: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
a880: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
a890: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
a8a0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
a8b0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
a8c0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
a8d0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
a8e0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
a8f0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
a900: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
a910: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
a920: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
a930: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
a940: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
a950: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
a960: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
a970: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
a980: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
a990: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
a9a0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
a9b0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
a9c0: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
a9d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
a9e0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
a9f0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
aa00: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
aa10: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
aa20: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
aa30: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
aa40: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
aa50: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
aa60: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
aa70: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
aa80: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
aa90: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
aaa0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
aab0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
aac0: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
aad0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
aae0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
aaf0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
ab00: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
ab10: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
ab20: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
ab30: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
ab40: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
ab50: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
ab60: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
ab70: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
ab80: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
ab90: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
aba0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
abb0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
abc0: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
abd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
abe0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
abf0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
ac00: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
ac10: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
ac20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ac30: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
ac40: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
ac50: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
ac60: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
ac70: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
ac80: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
ac90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aca0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
acb0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
acc0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
acd0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
ace0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
acf0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
ad00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ad10: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
ad20: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
ad30: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
ad40: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ad50: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
ad60: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
ad70: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
ad80: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
ad90: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
ada0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
adb0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
adc0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
add0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ade0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
adf0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
ae00: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
ae10: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
ae20: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
ae30: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
ae40: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
ae50: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
ae60: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
ae70: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
ae80: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
ae90: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
aea0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
aeb0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
aec0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
aed0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
aee0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
aef0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
af00: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
af10: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
af20: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
af30: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
af40: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
af50: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
af60: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
af70: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
af80: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
af90: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
afa0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
afb0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
afc0: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
afd0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
afe0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
aff0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
b000: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
b010: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
b020: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
b030: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
b040: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
b050: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
b060: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
b070: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
b080: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
b090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
b0a0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
b0b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b0c0: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
b0d0: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
b0e0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b0f0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
b100: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
b110: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
b120: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
b130: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
b140: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
b150: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
b160: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
b170: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
b180: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
b190: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
b1a0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
b1b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b1c0: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
b1d0: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
b1e0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
b1f0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
b200: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
b210: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b220: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
b230: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
b240: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
b250: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
b260: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
b270: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
b280: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
b290: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
b2a0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
b2b0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
b2c0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
b2d0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
b2e0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
b2f0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
b300: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
b310: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
b320: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
b330: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
b340: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
b350: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
b360: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
b370: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
b380: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
b390: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
b3a0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
b3b0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
b3c0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
b3d0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
b3e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b3f0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
b400: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
b410: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
b420: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
b430: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
b440: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b450: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
b460: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
b470: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
b480: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
b490: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
b4a0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
b4b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
b4c0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
b4d0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
b4e0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
b4f0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
b500: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
b510: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b520: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
b530: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
b540: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
b550: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b560: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
b570: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
b580: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
b590: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
b5a0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
b5b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b5c0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
b5d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
b5e0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
b5f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
b600: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
b610: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
b620: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
b630: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b640: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
b650: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
b660: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b670: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
b680: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
b690: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
b6a0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
b6b0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
b6c0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
b6d0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
b6e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
b6f0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
b700: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
b710: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
b720: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
b730: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
b740: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
b750: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
b760: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
b770: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
b780: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
b790: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
b7a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
b7b0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
b7c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
b7d0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
b7e0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
b7f0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
b800: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
b810: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
b820: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
b830: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
b840: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
b850: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b860: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
b870: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
b880: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
b890: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
b8a0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
b8b0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
b8c0: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
b8d0: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
b8e0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
b8f0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b900: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
b910: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b920: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
b930: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
b940: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
b950: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
b960: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
b970: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
b980: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
b990: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
b9a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b9b0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
b9c0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
b9d0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
b9e0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
b9f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
ba00: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
ba10: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
ba20: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
ba30: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
ba40: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
ba50: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
ba60: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
ba70: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
ba80: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
ba90: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
baa0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
bab0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
bac0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
bad0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
bae0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
baf0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
bb00: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
bb10: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
bb20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
bb30: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
bb40: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
bb50: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
bb60: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
bb70: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
bb80: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
bb90: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
bba0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
bbb0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
bbc0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
bbd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
bbe0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
bbf0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
bc00: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
bc10: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
bc20: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
bc30: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
bc40: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
bc50: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
bc60: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
bc70: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
bc80: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
bc90: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
bca0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
bcb0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
bcc0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
bcd0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
bce0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
bcf0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
bd00: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
bd10: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
bd20: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
bd30: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
bd40: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
bd50: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
bd60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
bd70: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
bd80: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
bd90: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
bda0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
bdb0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
bdc0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
bdd0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
bde0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
bdf0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
be00: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
be10: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
be20: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
be30: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
be40: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
be50: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
be60: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
be70: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
be80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
be90: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
bea0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
beb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
bec0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
bed0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
bee0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
bef0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
bf00: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
bf10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
bf20: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
bf30: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
bf40: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
bf50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
bf60: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
bf70: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
bf80: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
bf90: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
bfa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bfb0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
bfc0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
bfd0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
bfe0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
bff0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
c000: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
c010: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c020: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
c030: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
c040: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
c050: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
c060: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
c070: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
c080: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
c090: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
c0a0: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
c0b0: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
c0c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
c0d0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
c0e0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
c0f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
c100: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
c110: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
c120: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
c130: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
c140: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
c150: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
c160: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
c170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
c180: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c190: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
c1a0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
c1b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
c1c0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
c1d0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
c1e0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
c1f0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
c200: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c210: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
c220: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c230: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
c240: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
c250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
c260: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
c270: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
c280: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
c290: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
c2a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
c2b0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
c2c0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
c2d0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
c2e0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
c2f0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
c300: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
c310: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
c320: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
c330: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
c340: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
c350: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
c360: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
c370: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
c380: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
c390: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
c3a0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
c3b0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
c3c0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
c3d0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
c3e0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
c3f0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
c400: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
c410: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
c420: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
c430: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
c440: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
c450: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
c460: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
c470: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
c480: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
c490: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
c4a0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
c4b0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
c4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
c4d0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
c4e0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
c4f0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
c500: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
c510: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c520: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
c530: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
c540: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
c550: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
c560: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
c570: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
c580: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
c590: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
c5a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c5b0: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
c5c0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
c5d0: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
c5e0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
c5f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
c600: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
c610: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
c620: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
c630: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
c640: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
c650: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
c660: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
c670: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
c680: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
c690: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
c6a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
c6b0: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
c6c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
c6d0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
c6e0: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
c6f0: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
c700: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
c710: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
c720: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
c730: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53  ending on the [S
c740: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
c750: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
c760: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c770: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
c780: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
c790: 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
c7a0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
c7b0: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
c7c0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
c7d0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
c7e0: 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
c7f0: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
c800: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
c810: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
c820: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
c830: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
c840: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
c850: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
c860: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
c870: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c880: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
c890: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c8a0: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
c8b0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c8c0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
c8d0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
c8e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
c8f0: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
c900: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c910: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
c920: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
c930: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
c940: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
c950: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
c960: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
c970: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
c980: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
c990: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
c9a0: 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68  t argument).  Th
c9b0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f  e.** sqlite3_db_
c9c0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
c9d0: 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62  ce should only b
c9e0: 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65  e used immediate
c9f0: 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20  ly after.** the 
ca00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ca10: 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75  ion is created u
ca20: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
ca30: 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  en()],.** [sqlit
ca40: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
ca50: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
ca60: 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  2()].  .**.** Th
ca70: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
ca80: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
ca90: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
caa0: 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69   is the.** confi
cab0: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20  guration verb - 
cac0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
cad0: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
cae0: 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66  hat.** aspect of
caf0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
cb00: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
cb10: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
cb20: 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69  ** The only choi
cb30: 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75  ce for this valu
cb40: 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43  e is [SQLITE_DBC
cb50: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
cb60: 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61  ..** New verbs a
cb70: 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20  re likely to be 
cb80: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
cb90: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
cba0: 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  te..** Additiona
cbb0: 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65  l arguments depe
cbc0: 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a  nd on the verb..
cbd0: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
cbe0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
cbf0: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
cc00: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
cc10: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
cc20: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
cc30: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
cc40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
cc50: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
cc60: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
cc70: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
cc80: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
cc90: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
cca0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ccb0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
ccc0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
ccd0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
cce0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
ccf0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
cd00: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
cd10: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
cd20: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
cd30: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
cd40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
cd50: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
cd60: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
cd70: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
cd80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
cd90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
cda0: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
cdb0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
cdc0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
cdd0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
cde0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
cdf0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
ce00: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
ce10: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ce20: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
ce30: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
ce40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
ce50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
ce60: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
ce70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
ce80: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
ce90: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
cea0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
ceb0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
cec0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
ced0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
cee0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
cef0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
cf00: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
cf10: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
cf20: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
cf30: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
cf40: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
cf50: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
cf60: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
cf70: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
cf80: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
cf90: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
cfa0: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
cfb0: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
cfc0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
cfd0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
cfe0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
cff0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
d000: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
d010: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
d020: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
d030: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
d040: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
d050: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
d060: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
d070: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
d080: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
d090: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
d0a0: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
d0b0: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
d0c0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
d0d0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
d0e0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
d0f0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
d100: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
d110: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
d120: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
d130: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
d140: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
d150: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
d160: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
d170: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c  ry..** The xReal
d180: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  loc method must 
d190: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f  work like reallo
d1a0: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61  c() from the sta
d1b0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a  ndard C library.
d1c0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65  ** with the exce
d1d0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68  ption that if th
d1e0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
d1f0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73  t to xRealloc is
d200: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c   zero,.** xReall
d210: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d  oc must be a no-
d220: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74  op - it must not
d230: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c   perform any all
d240: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65  ocation or.** de
d250: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51  allocation.  ^SQ
d260: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
d270: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
d280: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
d290: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
d2a0: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
d2b0: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
d2c0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
d2d0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73  ** And so in cas
d2e0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75  es where xRoundu
d2f0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  p always returns
d300: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
d310: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  er,.** xRealloc 
d320: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63  can perform exac
d330: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64  tly as the stand
d340: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c  ard library real
d350: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69  loc() and.** sti
d360: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61  ll be in complia
d370: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70  nce with this sp
d380: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  ecification..**.
d390: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
d3a0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
d3b0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
d3c0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d3d0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
d3e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
d3f0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
d400: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
d410: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
d420: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
d430: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
d440: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
d450: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
d460: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
d470: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
d480: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
d490: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
d4a0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
d4b0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
d4c0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
d4d0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
d4e0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
d4f0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
d500: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d510: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
d520: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
d530: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
d540: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
d550: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
d560: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
d570: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
d580: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
d590: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
d5a0: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
d5b0: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
d5c0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
d5d0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
d5e0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
d5f0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
d600: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
d610: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
d620: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
d630: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d640: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
d650: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
d660: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
d670: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d680: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
d690: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
d6a0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
d6b0: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
d6c0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
d6d0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
d6e0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
d6f0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
d700: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
d710: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
d720: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
d730: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
d740: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
d750: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
d760: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
d770: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
d780: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
d790: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
d7a0: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
d7b0: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
d7c0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
d7d0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
d7e0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
d7f0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
d800: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
d810: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
d820: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
d830: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
d840: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
d850: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
d860: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
d870: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
d880: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
d890: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
d8a0: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
d8b0: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
d8c0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
d8d0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
d8e0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
d8f0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
d900: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
d910: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
d920: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
d930: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d940: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
d950: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
d960: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
d970: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
d980: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
d990: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
d9a0: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
d9b0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
d9c0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
d9d0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
d9e0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
d9f0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
da00: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
da10: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
da20: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
da30: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
da40: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
da50: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
da60: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
da70: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
da80: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
da90: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
daa0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
dab0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
dac0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
dad0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
dae0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
daf0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
db00: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
db10: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
db20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
db30: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
db40: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
db50: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
db60: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
db70: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
db80: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
db90: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
dba0: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
dbb0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
dbc0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
dbd0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
dbe0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
dbf0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
dc00: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
dc10: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
dc20: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
dc30: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
dc40: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
dc50: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
dc60: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
dc70: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
dc80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
dc90: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
dca0: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
dcb0: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
dcc0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
dcd0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
dce0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
dcf0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
dd00: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
dd10: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
dd20: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
dd30: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
dd40: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
dd50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
dd60: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
dd70: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
dd80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dd90: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
dda0: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
ddb0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ddc0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
ddd0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
dde0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
ddf0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
de00: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
de10: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
de20: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
de30: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
de40: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
de50: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
de60: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
de70: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
de80: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
de90: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
dea0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
deb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
dec0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
ded0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
dee0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
def0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
df00: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
df10: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
df20: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
df30: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
df40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
df50: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
df60: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
df70: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
df80: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
df90: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
dfa0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
dfb0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
dfc0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
dfd0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
dfe0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dff0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
e000: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
e010: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
e020: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
e030: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
e040: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
e050: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
e060: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
e070: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
e080: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
e090: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
e0a0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
e0b0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
e0c0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
e0d0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
e0e0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
e0f0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
e100: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
e110: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
e120: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
e130: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
e140: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
e150: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
e160: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
e170: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
e180: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
e190: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
e1a0: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
e1b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e1c0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
e1d0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e1e0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
e1f0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
e200: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
e210: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
e220: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
e230: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
e240: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
e250: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
e260: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
e270: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
e280: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
e290: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
e2a0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
e2b0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
e2c0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e2d0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
e2e0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
e2f0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
e300: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e310: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
e320: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
e330: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
e340: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
e350: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
e360: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
e370: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
e380: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
e390: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
e3a0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
e3b0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
e3c0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
e3d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e3e0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
e3f0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
e400: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e410: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
e420: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
e430: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e440: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
e450: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
e460: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
e470: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
e480: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
e490: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
e4a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
e4b0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
e4c0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
e4d0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
e4e0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
e4f0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
e500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e510: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
e520: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e530: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
e540: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
e550: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
e560: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
e570: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
e580: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
e590: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
e5a0: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
e5b0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
e5c0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
e5d0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
e5e0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
e5f0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
e600: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
e610: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
e620: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e630: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
e640: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
e650: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
e660: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
e670: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e680: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
e690: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
e6a0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
e6b0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
e6c0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
e6d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e6e0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
e6f0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
e700: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
e710: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
e720: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
e730: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
e740: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
e750: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
e760: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
e770: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
e780: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
e790: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
e7a0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e7b0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e7c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
e7d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e7e0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
e7f0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
e800: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
e810: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
e820: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
e830: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
e840: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
e850: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
e860: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
e870: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
e880: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
e890: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
e8a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e8b0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
e8c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e8d0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
e8e0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
e8f0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
e900: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
e910: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
e920: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
e930: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
e940: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
e950: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
e960: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
e970: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
e980: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
e990: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
e9a0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
e9b0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
e9c0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
e9d0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
e9e0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
e9f0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
ea00: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
ea10: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
ea20: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
ea30: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
ea40: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
ea50: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
ea60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ea70: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
ea80: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ea90: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
eaa0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
eab0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
eac0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ead0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
eae0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
eaf0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
eb00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
eb10: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
eb20: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
eb30: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
eb40: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
eb50: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
eb60: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
eb70: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
eb80: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
eb90: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
eba0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
ebb0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
ebc0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
ebd0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
ebe0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
ebf0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
ec00: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ec10: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
ec20: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
ec30: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
ec40: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
ec50: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ec60: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
ec70: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
ec80: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
ec90: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
eca0: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
ecb0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
ecc0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
ecd0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
ece0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
ecf0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
ed00: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
ed10: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
ed20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
ed30: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
ed40: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
ed50: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
ed60: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
ed70: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
ed80: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
ed90: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
eda0: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
edb0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
edc0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
edd0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
ede0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
edf0: 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
ee00: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
ee10: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
ee20: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
ee30: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
ee40: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
ee50: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
ee60: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
ee70: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
ee80: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
ee90: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
eea0: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
eeb0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
eec0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
eed0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
eee0: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
eef0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ef00: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
ef10: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
ef20: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
ef30: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
ef40: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
ef50: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
ef60: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
ef70: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
ef80: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
ef90: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
efa0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
efb0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
efc0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
efd0: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
efe0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
eff0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
f000: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
f010: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
f020: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
f030: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
f040: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
f050: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
f060: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
f070: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
f080: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f090: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
f0a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
f0b0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
f0c0: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
f0d0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
f0e0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
f0f0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
f100: 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
f110: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
f120: 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
f130: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
f140: 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
f150: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
f160: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
f170: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
f180: 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
f190: 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
f1a0: 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
f1b0: 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
f1c0: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
f1d0: 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
f1e0: 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
f1f0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
f200: 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
f210: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
f220: 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
f230: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
f240: 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
f250: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
f260: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
f270: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
f280: 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
f290: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f2a0: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
f2b0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
f2c0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
f2d0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
f2e0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
f2f0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
f300: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
f310: 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
f320: 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
f330: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61   cache implemena
f340: 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
f350: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
f360: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
f370: 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
f380: 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
f390: 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
f3a0: 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
f3b0: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
f3c0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
f3d0: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
f3e0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
f3f0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
f400: 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
f410: 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
f420: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
f430: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
f440: 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
f450: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
f460: 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
f470: 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
f480: 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
f490: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
f4a0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
f4b0: 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
f4c0: 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
f4d0: 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
f4e0: 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
f4f0: 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
f500: 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
f510: 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
f520: 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
f530: 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
f540: 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
f550: 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
f560: 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
f570: 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
f580: 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
f590: 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
f5a0: 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
f5b0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
f5c0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
f5d0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
f5e0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
f5f0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
f600: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f610: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
f620: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
f630: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
f640: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
f650: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
f660: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
f670: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
f680: 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
f690: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
f6a0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
f6b0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
f6c0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
f6d0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
f6e0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
f6f0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
f700: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
f710: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
f720: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
f730: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
f740: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f750: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
f760: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
f770: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
f780: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
f790: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
f7a0: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
f7b0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f7c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
f7d0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
f7e0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f7f0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f800: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f810: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
f820: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
f830: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
f840: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
f850: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
f860: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
f870: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
f880: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
f890: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f8a0: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
f8b0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
f8c0: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
f8d0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
f8e0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
f8f0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
f900: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
f910: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
f920: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
f930: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
f940: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
f950: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
f960: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
f970: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
f980: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
f990: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
f9a0: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
f9b0: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
f9c0: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
f9d0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
f9e0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
f9f0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
fa00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fa10: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
fa20: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
fa30: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
fa40: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
fa50: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
fa60: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
fa70: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
fa80: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
fa90: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
faa0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
fab0: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
fac0: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
fad0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
fae0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
faf0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
fb00: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
fb10: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
fb20: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
fb30: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
fb40: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
fb50: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
fb60: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
fb70: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
fb80: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
fb90: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
fba0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
fbb0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
fbc0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
fbd0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
fbe0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
fbf0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
fc00: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
fc10: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
fc20: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
fc30: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
fc40: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
fc50: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
fc60: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
fc70: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
fc80: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
fc90: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
fca0: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
fcb0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
fcc0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
fcd0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
fce0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
fcf0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
fd00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
fd10: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
fd20: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
fd30: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
fd40: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
fd50: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
fd60: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
fd70: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
fd80: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
fd90: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
fda0: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
fdb0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
fdc0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
fdd0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
fde0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
fdf0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fe00: 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
fe10: 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
fe20: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
fe30: 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
fe40: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
fe50: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
fe60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
fe70: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
fe80: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
fe90: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
fea0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
feb0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
fec0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
fed0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
fee0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
fef0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ff00: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
ff10: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
ff20: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
ff30: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
ff40: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
ff50: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
ff60: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
ff70: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
ff80: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
ff90: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
ffa0: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
ffb0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
ffc0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
ffd0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
ffe0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
fff0: 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
10000 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10010 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
10020 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
10030 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10040 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
10050 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10060 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
10070 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
10080 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
10090 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
100a0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
100b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
100c0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
100d0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
100e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
100f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
10100 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
10110 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
10120 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10130 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
10140 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
10150 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
10160 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
10170 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
10180 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
10190 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
101a0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
101b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
101c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
101d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
101e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
101f0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
10200 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
10210 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
10220 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
10230 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
10240 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
10250 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
10260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
10270 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
10280 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
10290 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
102a0 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
102b0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
102c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
102d0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
102e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
102f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
10300 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
10310 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
10320 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
10330 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
10340 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
10350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
10360 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10370 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10380 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10390 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
103a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
103b0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
103c0 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
103d0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
103e0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
103f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
10400 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
10410 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
10420 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
10430 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
10440 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
10450 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
10460 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
10470 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
10480 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
10490 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
104a0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
104b0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
104c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
104d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
104e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
104f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
10500 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
10510 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
10520 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
10530 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
10540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
10550 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
10560 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
10570 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10580 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
10590 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
105a0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
105b0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
105c0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
105d0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
105e0 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
105f0 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
10600 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
10610 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
10620 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
10630 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
10640 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
10650 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
10660 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
10670 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
10680 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
10690 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
106a0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
106b0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
106c0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
106d0 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
106e0 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
106f0 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
10700 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
10710 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10720 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
10730 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
10740 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
10750 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
10760 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
10770 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
10780 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
10790 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
107a0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
107b0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
107c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
107d0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
107e0 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
107f0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
10800 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
10810 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
10820 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
10830 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
10840 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
10850 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
10860 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
10870 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
10880 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
10890 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
108a0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
108b0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
108c0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
108d0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
108e0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
108f0 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
10900 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
10910 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
10920 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
10930 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
10940 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
10950 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
10960 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
10970 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
10980 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
10990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
109a0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
109b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
109c0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
109d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
109e0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
109f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
10a00 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
10a10 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10a20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10a30 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
10a40 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10a60 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
10a70 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10a80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10a90 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
10aa0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
10ab0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
10ac0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10ad0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
10ae0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
10af0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10b00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10b10 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
10b20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
10b30 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
10b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10b50 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
10b60 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
10b70 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10b80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10b90 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
10ba0 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
10bb0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
10bc0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
10bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
10be0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
10bf0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
10c00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10c10 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
10c20 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
10c30 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10c40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10c50 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
10c60 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
10c70 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
10c80 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
10c90 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
10ca0 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
10cb0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
10cc0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
10cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10ce0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
10cf0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
10d00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10d10 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
10d20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
10d30 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
10d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10d50 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
10d60 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
10d70 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
10d80 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10d90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
10da0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
10db0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
10dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10dd0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
10de0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
10df0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
10e00 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10e10 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10e20 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10e30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10e40 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10e50 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
10e60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10e70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
10e80 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10e90 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
10ea0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10eb0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
10ec0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
10ed0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
10ee0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
10ef0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10f00 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
10f10 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
10f20 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
10f30 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
10f40 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
10f50 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10f60 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10f70 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10f80 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
10f90 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10fa0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
10fb0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
10fc0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10fd0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
10fe0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
10ff0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
11000 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
11010 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11020 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
11030 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11040 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
11050 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
11060 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
11070 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
11080 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
11090 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
110a0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
110b0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
110c0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
110d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
110e0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
110f0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
11100 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
11110 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
11120 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
11130 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
11140 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
11150 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
11160 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
11170 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11180 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
11190 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
111a0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
111b0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
111c0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
111d0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
111e0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
111f0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
11200 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11210 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
11220 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
11230 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
11240 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
11250 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
11260 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
11270 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11280 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
11290 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
112a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
112b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
112c0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
112d0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
112e0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
112f0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
11300 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
11310 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
11320 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
11330 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
11340 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
11350 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
11360 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11370 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
11380 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
11390 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
113a0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
113b0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
113c0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
113d0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
113e0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
113f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
11400 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
11410 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
11420 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
11430 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
11440 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
11450 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
11460 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
11470 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
11480 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
11490 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
114a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
114b0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
114c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
114d0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
114e0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
114f0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
11500 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
11510 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
11520 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
11530 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
11540 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
11550 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
11560 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
11570 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
11580 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
11590 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
115a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
115b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
115c0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
115d0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a   int int */.../*
115e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
115f0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
11600 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
11610 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
11620 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
11630 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
11640 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
11650 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
11660 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
11670 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
11680 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
11690 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
116a0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
116b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
116c0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
116d0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
116e0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
116f0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
11700 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
11710 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
11720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
11730 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
11740 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
11750 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
11760 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
11770 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
11780 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
11790 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
117a0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
117b0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
117c0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
117d0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
117e0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
117f0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
11800 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
11810 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
11820 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
11830 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
11840 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
11850 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
11860 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
11870 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
11880 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
11890 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
118a0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
118b0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
118c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
118d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
118e0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
118f0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
11900 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
11910 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
11920 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
11930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11940 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
11950 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
11960 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
11970 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
11980 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
11990 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
119a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
119b0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
119c0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
119d0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
119e0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
119f0 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
11a00 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
11a10 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
11a20 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
11a30 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
11a40 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
11a50 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
11a60 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
11a70 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
11a80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11a90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
11aa0 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
11ab0 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
11ac0 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
11ad0 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
11ae0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
11af0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
11b00 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
11b10 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
11b20 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
11b30 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
11b40 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
11b50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11b60 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
11b70 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
11b80 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
11b90 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
11ba0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
11bb0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
11bc0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
11bd0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
11be0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
11bf0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
11c00 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
11c10 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
11c20 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
11c30 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
11c40 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
11c50 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
11c60 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
11c70 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
11c80 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
11c90 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
11ca0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
11cb0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
11cc0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
11cd0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
11ce0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
11cf0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
11d00 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
11d10 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
11d20 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
11d30 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
11d40 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
11d50 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
11d60 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
11d70 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
11d80 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
11d90 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
11da0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
11db0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
11dc0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
11dd0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
11de0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
11df0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
11e00 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
11e10 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
11e20 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
11e30 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
11e40 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
11e50 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
11e60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
11e70 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11e80 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
11e90 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
11ea0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
11eb0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
11ec0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
11ed0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11ee0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
11ef0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
11f00 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
11f10 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
11f20 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
11f30 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
11f40 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
11f50 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
11f60 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
11f70 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
11f80 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
11f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11fa0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
11fb0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
11fc0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
11fd0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
11fe0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
11ff0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
12000 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
12010 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
12020 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
12030 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
12040 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
12050 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
12060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12070 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
12080 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12090 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
120a0 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
120b0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
120c0 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
120d0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
120e0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
120f0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
12100 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
12110 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
12120 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
12130 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
12140 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
12150 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
12160 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
12170 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
12180 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
12190 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
121a0 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
121b0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
121c0 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
121d0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
121e0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
121f0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
12200 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
12210 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
12220 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
12230 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
12240 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
12250 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
12260 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
12270 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
12280 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
12290 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
122a0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
122b0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
122c0 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
122d0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
122e0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
122f0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
12300 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
12310 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
12320 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
12330 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
12340 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
12350 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
12360 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
12370 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
12380 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
12390 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
123a0 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
123b0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
123c0 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
123d0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
123e0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
123f0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
12400 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
12410 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
12420 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
12430 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
12440 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
12450 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
12460 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
12470 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
12480 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
12490 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
124a0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
124b0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
124c0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
124d0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
124e0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
124f0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
12500 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
12510 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
12520 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
12530 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
12540 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
12550 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
12560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
12570 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
12580 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
12590 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
125a0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
125b0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
125c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
125d0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
125e0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
125f0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
12600 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
12610 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
12620 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
12630 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
12640 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
12650 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
12660 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
12670 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
12680 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
12690 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
126a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
126b0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
126c0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
126d0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
126e0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
126f0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
12700 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
12710 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
12720 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
12730 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
12740 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
12750 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
12760 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
12770 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
12780 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
12790 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
127a0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
127b0 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
127c0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
127d0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
127e0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
127f0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
12800 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
12810 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
12820 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
12830 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
12840 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
12850 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
12860 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
12870 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
12880 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
12890 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
128a0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
128b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
128c0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
128d0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
128e0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
128f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
12900 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
12910 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
12920 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
12930 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
12940 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
12950 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
12960 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
12970 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
12980 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
12990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
129a0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
129b0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
129c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
129d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
129e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
129f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
12a00 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
12a10 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
12a20 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
12a30 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
12a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
12a50 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
12a60 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
12a70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
12a80 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
12a90 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
12aa0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
12ab0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
12ac0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
12ad0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
12ae0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
12af0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
12b00 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
12b10 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
12b20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
12b30 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
12b40 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
12b50 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
12b60 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
12b70 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
12b80 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
12b90 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
12ba0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
12bb0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
12bc0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
12bd0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
12be0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
12bf0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
12c00 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
12c10 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
12c20 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
12c30 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
12c40 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
12c50 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
12c60 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
12c70 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
12c80 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
12c90 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
12ca0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
12cb0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
12cc0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
12cd0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
12ce0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
12cf0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
12d00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
12d10 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
12d20 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
12d30 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
12d40 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
12d50 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
12d60 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
12d70 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
12d80 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12d90 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12da0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
12db0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
12dc0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
12dd0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
12de0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
12df0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
12e00 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
12e10 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
12e20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
12e30 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
12e40 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
12e50 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
12e60 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
12e70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
12e80 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
12e90 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
12ea0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
12eb0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
12ec0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
12ed0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
12ee0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
12ef0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
12f00 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
12f10 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
12f20 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
12f30 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
12f40 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
12f50 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
12f60 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
12f70 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
12f80 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
12f90 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
12fa0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
12fb0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
12fc0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
12fd0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
12fe0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
12ff0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
13000 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
13010 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
13020 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
13030 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
13040 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
13050 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
13060 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
13070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13080 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
13090 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
130a0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
130b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
130c0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
130d0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
130e0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
130f0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
13100 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
13110 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
13120 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
13130 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
13140 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
13150 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
13160 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
13170 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
13180 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
13190 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
131a0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
131b0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
131c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
131d0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
131e0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
131f0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
13200 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
13210 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
13220 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
13230 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
13240 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
13250 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
13260 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
13270 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
13280 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
13290 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
132a0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
132b0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
132c0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
132d0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
132e0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
132f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13300 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
13310 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
13320 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
13330 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
13340 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
13350 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
13360 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
13370 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
13380 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
13390 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
133a0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
133b0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
133c0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
133d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
133e0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
133f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
13400 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
13410 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
13420 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
13430 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
13440 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
13450 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
13460 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
13470 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
13480 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
13490 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
134a0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
134b0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
134c0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
134d0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
134e0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
134f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
13500 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
13510 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
13520 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
13530 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
13540 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
13550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
13560 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
13570 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
13580 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
13590 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
135a0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
135b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
135c0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
135d0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
135e0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
135f0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
13600 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
13610 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13620 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
13630 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
13640 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
13650 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
13660 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
13670 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
13680 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
13690 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
136a0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
136b0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
136c0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
136d0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
136e0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
136f0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
13700 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13710 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
13720 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
13730 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
13740 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
13750 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
13760 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
13770 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
13780 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
13790 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
137a0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
137b0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
137c0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
137d0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
137e0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
137f0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
13800 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
13810 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
13820 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
13830 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
13840 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
13850 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
13860 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
13870 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
13880 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
13890 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
138a0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
138b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
138c0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
138d0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
138e0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
138f0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
13900 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
13910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
13920 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13930 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
13940 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
13950 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
13960 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13970 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
13980 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
13990 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
139a0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
139b0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
139c0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
139d0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
139e0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
139f0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
13a00 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
13a10 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
13a20 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
13a30 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
13a40 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
13a50 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
13a60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13a70 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
13a80 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
13a90 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
13aa0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
13ab0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
13ac0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
13ad0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
13ae0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
13af0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
13b00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13b10 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
13b20 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
13b30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
13b40 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
13b50 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
13b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
13b70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
13b80 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
13b90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
13ba0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
13bb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
13bc0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
13bd0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
13be0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
13bf0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
13c00 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
13c10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
13c20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
13c30 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
13c40 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
13c50 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13c60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
13c70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13c80 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
13c90 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
13ca0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
13cb0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
13cc0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
13cd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
13ce0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
13cf0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
13d00 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
13d10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
13d20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
13d30 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
13d40 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
13d50 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
13d60 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
13d70 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
13d80 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
13d90 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
13da0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
13db0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
13dc0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
13dd0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
13de0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
13df0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
13e00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
13e10 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
13e20 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
13e30 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
13e40 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
13e50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
13e60 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13e70 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
13e80 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
13e90 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
13ea0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
13eb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
13ec0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
13ed0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13ee0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
13ef0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
13f00 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13f10 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
13f20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
13f30 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
13f40 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
13f50 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
13f60 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
13f70 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
13f80 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
13f90 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
13fa0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
13fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
13fc0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
13fd0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
13fe0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
13ff0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
14000 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
14010 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
14020 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
14030 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
14040 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
14050 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
14060 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
14070 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
14080 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
14090 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
140a0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
140b0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
140c0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
140d0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
140e0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
140f0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
14100 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
14110 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
14120 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
14130 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
14140 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
14150 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
14160 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
14170 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
14180 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
14190 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
141a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
141b0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
141c0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
141d0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
141e0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
141f0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
14200 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
14210 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
14220 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
14230 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
14240 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
14250 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
14260 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
14270 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
14280 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
14290 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
142a0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
142b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
142c0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
142d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
142e0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
142f0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
14300 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
14310 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
14320 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
14330 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
14340 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
14350 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
14360 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
14370 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
14380 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
14390 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
143a0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
143b0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
143c0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
143d0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
143e0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
143f0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
14400 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
14410 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
14420 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
14430 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
14440 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
14450 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
14460 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
14470 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
14480 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14490 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
144a0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
144b0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
144c0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
144d0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
144e0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
144f0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
14500 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
14510 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
14520 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
14530 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
14540 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
14550 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
14560 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
14570 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
14580 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
14590 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
145a0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
145b0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
145c0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
145d0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
145e0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
145f0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
14600 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
14610 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
14620 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
14630 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
14640 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
14650 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
14660 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
14670 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
14680 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
14690 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
146a0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
146b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
146c0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
146d0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
146e0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
146f0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
14700 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
14710 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
14720 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
14730 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
14740 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
14750 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
14760 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
14770 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
14780 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
14790 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
147a0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
147b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
147c0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
147d0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
147e0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
147f0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
14800 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
14810 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
14820 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
14830 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
14840 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
14850 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
14860 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
14870 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
14880 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
14890 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
148a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
148b0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
148c0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
148d0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
148e0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
148f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
14900 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
14910 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
14920 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
14930 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
14940 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
14950 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
14960 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
14970 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
14980 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14990 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
149a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
149b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
149c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
149d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
149e0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
149f0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
14a00 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
14a10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14a20 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
14a30 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
14a40 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
14a50 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
14a60 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
14a70 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
14a80 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
14a90 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
14aa0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
14ab0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
14ac0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
14ad0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
14ae0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
14af0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
14b00 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
14b10 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
14b20 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
14b30 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
14b40 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
14b50 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
14b60 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
14b70 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
14b80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
14b90 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
14ba0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
14bb0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
14bc0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
14bd0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
14be0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
14bf0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
14c00 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
14c10 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
14c20 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
14c30 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
14c40 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
14c50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
14c60 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
14c70 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
14c80 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
14c90 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
14ca0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
14cb0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
14cc0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
14cd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
14ce0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
14cf0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
14d00 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
14d10 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
14d20 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
14d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
14d40 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
14d50 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
14d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14d70 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
14d80 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
14d90 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
14da0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
14db0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
14dc0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
14dd0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
14de0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
14df0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
14e00 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
14e10 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
14e20 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
14e30 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
14e40 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
14e50 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
14e60 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
14e70 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
14e80 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
14e90 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
14ea0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
14eb0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
14ec0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
14ed0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
14ee0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
14ef0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
14f00 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
14f10 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
14f20 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
14f30 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
14f40 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14f50 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
14f60 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
14f70 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
14f80 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
14f90 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
14fa0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
14fb0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
14fc0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
14fd0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
14fe0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
14ff0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
15000 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
15010 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
15020 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
15030 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
15040 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
15050 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
15060 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
15070 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
15080 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
15090 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
150a0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
150b0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
150c0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
150d0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
150e0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
150f0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
15100 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
15110 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
15120 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
15130 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
15140 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
15150 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
15160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
15170 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
15180 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
15190 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
151a0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
151b0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
151c0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
151d0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
151e0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
151f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
15200 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
15210 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
15220 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
15230 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
15240 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
15250 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
15260 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
15270 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
15280 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
15290 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
152a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
152b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
152c0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
152d0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
152e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
152f0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
15300 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
15310 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
15320 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
15330 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
15340 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
15350 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15360 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
15370 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
15380 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
15390 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
153a0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
153b0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
153c0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
153d0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
153e0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
153f0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
15400 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
15410 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
15420 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
15430 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15440 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15450 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
15460 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15470 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
15480 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
15490 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
154a0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
154b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
154c0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
154d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
154e0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
154f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15500 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
15510 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
15520 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
15530 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
15540 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
15550 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
15560 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
15570 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
15580 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15590 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
155a0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
155b0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
155c0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
155d0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
155e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
155f0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
15600 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
15610 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
15620 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
15630 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
15640 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
15650 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
15660 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
15670 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
15680 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
15690 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
156a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
156b0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
156c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
156d0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
156e0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
156f0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
15700 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
15710 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
15720 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
15730 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
15740 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15750 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
15760 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
15770 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
15780 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
15790 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
157a0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
157b0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
157c0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
157d0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
157e0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
157f0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
15800 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
15810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
15820 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
15830 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
15840 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
15850 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
15860 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
15870 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
15880 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
15890 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
158a0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
158b0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
158c0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
158d0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
158e0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
158f0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
15900 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
15910 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
15920 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
15930 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
15940 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
15950 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
15960 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
15970 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
15980 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
15990 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
159a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
159b0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
159c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
159d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
159e0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
159f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
15a00 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
15a10 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
15a20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
15a30 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
15a40 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
15a50 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
15a60 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
15a70 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
15a80 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
15a90 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
15aa0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
15ab0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15ac0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
15ad0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
15ae0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
15af0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
15b00 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
15b10 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
15b20 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
15b30 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
15b40 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
15b50 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
15b60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15b70 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
15b80 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
15b90 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
15ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
15bb0 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
15bc0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
15bd0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
15be0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
15bf0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
15c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
15c10 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
15c20 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
15c30 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
15c40 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
15c50 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
15c60 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
15c70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15c80 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
15c90 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
15ca0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
15cb0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
15cc0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
15cd0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
15ce0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
15cf0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
15d00 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
15d10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
15d20 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
15d30 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
15d40 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
15d50 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
15d60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
15d70 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
15d80 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
15d90 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
15da0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
15db0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
15dc0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
15dd0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
15de0 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
15df0 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
15e00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
15e10 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
15e20 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
15e30 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
15e40 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
15e50 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
15e60 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
15e70 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
15e80 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
15e90 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
15ea0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
15eb0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
15ec0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
15ed0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
15ee0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15ef0 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
15f00 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
15f10 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
15f20 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15f30 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
15f40 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
15f50 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
15f60 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
15f70 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
15f80 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
15f90 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
15fa0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
15fb0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
15fc0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
15fd0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
15fe0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
15ff0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
16000 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
16010 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
16020 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
16030 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
16040 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
16050 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
16060 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
16070 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
16080 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
16090 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
160a0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
160b0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
160c0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
160d0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
160e0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
160f0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
16100 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
16110 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
16120 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
16130 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
16140 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
16150 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
16160 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
16170 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
16180 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
16190 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
161a0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
161b0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
161c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
161d0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
161e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
161f0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
16200 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
16210 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
16220 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
16230 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
16240 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
16250 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
16260 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
16270 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
16280 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
16290 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
162a0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
162b0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
162c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
162d0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
162e0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
162f0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
16300 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
16310 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
16320 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
16330 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
16340 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
16350 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
16360 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
16370 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
16380 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
16390 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
163a0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
163b0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
163c0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
163d0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
163e0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
163f0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
16400 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
16410 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
16420 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
16430 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
16440 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
16450 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16460 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
16470 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
16480 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
16490 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
164a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
164b0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
164c0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
164d0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
164e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
164f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
16500 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
16510 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
16520 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
16530 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
16540 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16550 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16560 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16570 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
165a0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
165b0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
165c0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
165d0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
165e0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
165f0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
16600 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
16610 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
16620 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16630 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
16640 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
16650 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
16660 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16670 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
16680 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
16690 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
166a0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
166b0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
166c0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
166d0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
166e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
166f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
16700 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
16710 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
16720 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
16730 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16740 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
16750 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
16760 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
16770 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
16780 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
16790 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
167a0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
167b0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
167c0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
167d0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
167e0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
167f0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
16800 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
16810 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
16820 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
16830 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
16840 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
16850 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
16860 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
16870 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
16880 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
16890 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
168a0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
168b0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
168c0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
168d0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
168e0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
168f0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
16900 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
16910 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
16920 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16930 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
16940 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
16950 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
16960 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
16970 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
16980 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
16990 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
169a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
169b0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
169c0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
169d0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
169e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
169f0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
16a00 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
16a10 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
16a20 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
16a30 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
16a40 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
16a50 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
16a60 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
16a70 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
16a80 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
16a90 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
16aa0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
16ab0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
16ac0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
16ad0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
16ae0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
16af0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
16b00 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
16b10 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
16b20 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
16b30 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
16b40 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
16b50 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
16b60 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16b70 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
16b80 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
16b90 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
16ba0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
16bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16bc0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
16bd0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
16be0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
16bf0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
16c00 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
16c10 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
16c20 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
16c30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16c40 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
16c50 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
16c60 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
16c70 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
16c80 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
16c90 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
16ca0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
16cb0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
16cc0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
16cd0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
16ce0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
16cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
16d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
16d10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
16d20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
16d30 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
16d40 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
16d50 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
16d60 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
16d70 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
16d80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
16d90 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
16da0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
16db0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
16dc0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
16dd0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
16de0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
16df0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
16e00 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
16e10 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
16e20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
16e30 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
16e40 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
16e50 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
16e60 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
16e70 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
16e80 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
16e90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16ea0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
16eb0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
16ec0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
16ed0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
16ee0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
16ef0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
16f00 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
16f10 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
16f20 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
16f30 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
16f40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
16f50 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
16f60 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
16f70 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
16f80 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
16f90 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
16fa0 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
16fb0 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
16fc0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
16fd0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
16fe0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
16ff0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
17000 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
17010 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
17020 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
17030 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
17040 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
17050 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
17060 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
17070 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
17080 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
17090 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
170a0 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
170b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
170c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
170d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
170e0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
170f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17100 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
17110 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
17120 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
17130 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
17140 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17150 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
17160 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
17170 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
17180 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
17190 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
171a0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
171b0 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
171c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
171d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
171e0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
171f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
17200 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
17210 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
17220 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
17230 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
17240 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
17250 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
17260 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
17270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
17280 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17290 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
172a0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
172b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
172c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
172d0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
172e0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
172f0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
17300 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
17310 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17330 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
17340 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
17350 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
17360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17370 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
17380 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
17390 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
173a0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
173b0 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
173c0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
173d0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
173e0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
173f0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
17400 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
17410 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
17420 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
17430 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
17440 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
17450 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17460 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
17470 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
17480 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
17490 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
174a0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
174b0 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
174c0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
174d0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
174e0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
174f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
17500 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
17510 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
17520 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
17530 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
17540 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
17550 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
17560 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
17570 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
17580 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
17590 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
175a0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
175b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
175c0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
175d0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
175e0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
175f0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
17600 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
17610 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
17620 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
17630 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
17640 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
17650 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
17660 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
17670 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
17680 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
17690 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
176a0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
176b0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
176c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
176d0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
176e0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73  face layer calls
176f0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
17700 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
17710 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
17720 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
17730 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
17740 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
17750 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
17760 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
17770 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
17780 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
17790 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
177a0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
177b0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
177c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
177d0 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20  s are detected, 
177e0 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  but.** they are 
177f0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
17800 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
17810 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
17820 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
17830 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
17840 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
17850 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
17860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
17870 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
17880 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
17890 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
178a0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
178b0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
178c0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
178d0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
178e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
178f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17900 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
17910 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
17920 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
17930 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
17940 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
17950 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
17960 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
17970 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
17980 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
17990 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
179a0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
179b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
179c0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
179d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
179e0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
179f0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
17a00 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
17a10 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
17a20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17a30 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
17a40 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
17a50 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
17a60 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
17a70 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
17a80 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
17a90 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
17aa0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
17ab0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17ac0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
17ad0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
17ae0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
17af0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
17b00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17b10 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
17b20 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
17b30 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
17b40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
17b50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
17b60 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
17b70 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
17b80 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
17b90 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
17ba0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
17bb0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
17bc0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
17bd0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
17be0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
17bf0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17c00 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
17c10 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
17c20 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
17c30 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
17c40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
17c50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
17c60 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
17c70 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
17c80 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
17c90 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
17ca0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
17cb0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
17cc0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
17cd0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
17ce0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
17cf0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
17d00 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
17d10 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
17d20 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
17d30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
17d40 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
17d50 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
17d60 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
17d70 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
17d80 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
17d90 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
17da0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
17db0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
17dc0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
17dd0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
17de0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
17df0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
17e00 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
17e10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
17e20 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
17e30 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
17e40 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
17e50 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
17e60 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
17e70 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
17e80 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
17e90 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
17ea0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
17eb0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
17ec0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
17ed0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
17ee0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
17ef0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
17f00 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
17f10 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
17f20 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
17f30 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
17f40 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
17f50 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
17f60 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
17f70 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
17f80 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
17f90 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
17fa0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
17fb0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
17fc0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
17fd0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
17fe0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
17ff0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
18000 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
18010 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
18020 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
18030 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
18040 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
18050 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
18060 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
18070 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
18080 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
18090 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
180a0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
180b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
180c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
180d0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
180e0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
180f0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
18100 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
18110 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
18120 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
18130 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
18140 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
18150 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
18160 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
18170 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
18180 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
18190 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
181a0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
181b0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
181c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
181d0 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
181e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
181f0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
18200 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
18210 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
18220 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
18230 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
18240 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
18250 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
18260 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
18270 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
18280 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
18290 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
182a0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
182b0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
182c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
182d0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
182e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
182f0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
18300 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
18310 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
18320 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
18330 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
18340 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18350 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
18360 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
18370 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
18380 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18390 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
183a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
183b0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
183c0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
183d0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
183e0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
183f0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
18400 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
18410 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
18420 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
18430 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
18440 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
18450 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
18460 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
18470 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
18480 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
18490 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
184a0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
184b0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
184c0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
184d0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
184e0 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
184f0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
18500 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
18510 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
18520 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
18530 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
18540 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
18550 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
18560 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
18570 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
18580 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
18590 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
185a0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
185b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
185c0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
185d0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
185e0 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
185f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
18600 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
18610 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
18620 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
18630 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18640 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
18650 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
18660 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
18670 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18680 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
18690 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
186a0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
186b0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
186c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
186d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
186e0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
186f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18700 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
18710 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
18720 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
18730 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
18740 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
18750 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
18760 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
18770 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
18780 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
18790 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
187a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
187b0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
187c0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
187d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
187e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
187f0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
18800 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
18810 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
18820 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
18830 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
18840 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
18850 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
18860 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
18870 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
18880 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
18890 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
188a0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
188b0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
188c0 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
188d0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
188e0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
188f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
18900 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
18910 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
18920 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
18930 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
18940 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
18950 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
18960 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18970 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
18980 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
18990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
189a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
189b0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
189c0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
189d0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
189e0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
189f0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
18a00 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
18a10 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
18a20 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
18a30 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
18a40 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
18a50 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
18a60 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
18a70 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
18a80 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
18a90 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
18aa0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
18ab0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
18ac0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
18ad0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
18ae0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
18af0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
18b00 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
18b10 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
18b20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
18b30 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
18b40 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
18b50 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
18b60 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
18b70 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
18b80 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
18b90 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
18ba0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
18bb0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
18bc0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
18bd0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
18be0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
18bf0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18c00 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
18c10 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
18c20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
18c30 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
18c40 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
18c50 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
18c60 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
18c70 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
18c80 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
18c90 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
18ca0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
18cb0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
18cc0 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
18cd0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
18ce0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
18cf0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
18d00 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
18d10 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
18d20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
18d30 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
18d40 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
18d50 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
18d60 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
18d70 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
18d80 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
18d90 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
18da0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
18db0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
18dc0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
18dd0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
18de0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
18df0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
18e00 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
18e10 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
18e20 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
18e30 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
18e40 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
18e50 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
18e60 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
18e70 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
18e80 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
18e90 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
18ea0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
18eb0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
18ec0 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
18ed0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
18ee0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
18ef0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
18f00 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
18f10 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
18f20 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
18f30 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
18f40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18f50 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
18f60 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
18f70 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18f80 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
18f90 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
18fa0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
18fb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
18fc0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
18fd0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
18fe0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
18ff0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
19000 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
19010 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19020 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
19030 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
19040 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
19050 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19060 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
19070 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
19080 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
19090 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
190a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
190b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
190c0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
190d0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
190e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
190f0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
19100 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
19110 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
19120 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
19130 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19140 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
19150 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
19160 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
19170 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
19180 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
19190 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
191a0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
191b0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
191c0 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
191d0 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
191e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
191f0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
19200 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
19210 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
19220 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
19230 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
19240 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
19250 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19260 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
19270 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
19280 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
19290 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
192a0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
192b0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
192c0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
192d0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
192e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
192f0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
19300 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
19310 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
19320 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
19330 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
19340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19350 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
19360 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
19370 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
19380 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19390 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
193a0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
193b0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
193c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
193d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
193e0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
193f0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
19400 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
19410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
19420 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
19430 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
19440 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19450 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
19460 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
19470 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
19480 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
19490 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
194a0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
194b0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
194c0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
194d0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
194e0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
194f0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
19500 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19510 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
19520 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
19530 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
19540 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
19550 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64  formation..*/.#d
19560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
19570 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
19580 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19590 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
195a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
195b0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
195c0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
195d0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
195e0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
195f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
19600 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
19610 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
19620 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
19630 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
19640 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
19650 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
19660 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
19670 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
19680 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
19690 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
196a0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
196b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
196c0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
196d0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
196e0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
196f0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
19700 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
19710 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
19720 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
19730 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
19740 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
19750 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
19760 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
19770 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
19780 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
19790 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
197a0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
197b0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
197c0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
197d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
197e0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
197f0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
19800 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
19810 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
19820 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
19830 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
19840 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
19850 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
19860 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
19870 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
19880 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
19890 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
198a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
198b0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
198c0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
198d0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
198e0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
198f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19900 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19910 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
19920 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
19930 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
19940 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
19950 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
19960 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
19970 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
19980 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
19990 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
199a0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
199b0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
199c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
199d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
199e0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
199f0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
19a00 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
19a10 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
19a20 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
19a30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19a40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19a50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19a60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
19a70 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
19a80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19a90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19aa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19ab0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
19ac0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
19ad0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19ae0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19af0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19b00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
19b10 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
19b20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19b30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19b40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19b50 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
19b60 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
19b70 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19ba0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
19bb0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
19bc0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19bd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19bf0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
19c00 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
19c10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
19c20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19c40 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
19c50 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
19c60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
19c70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19c90 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
19ca0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
19cb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19cc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19ce0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
19cf0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
19d00 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
19d10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19d30 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
19d40 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
19d50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19d60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19d80 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
19d90 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
19da0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
19db0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19dd0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
19de0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
19df0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
19e00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19e10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19e20 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
19e30 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
19e40 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19e50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19e60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19e70 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
19e80 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
19e90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19ea0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19eb0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
19ec0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
19ed0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
19ee0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
19ef0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19f00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
19f10 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
19f20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
19f30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19f40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19f50 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
19f60 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
19f70 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19f80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19f90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19fa0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
19fb0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
19fc0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
19fd0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
19fe0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
19ff0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1a000 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1a010 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a020 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1a030 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a040 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1a050 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1a060 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a070 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a080 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a090 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1a0a0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1a0b0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1a0c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a0d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a0e0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1a0f0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1a100 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1a110 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1a120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a130 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1a140 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1a150 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1a160 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a170 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a180 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1a190 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1a1a0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1a1b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1a1c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1a1d0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1a1e0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1a1f0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1a200 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1a210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1a220 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1a230 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1a240 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1a250 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a260 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1a270 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1a280 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1a290 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1a2a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a2b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a2c0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1a2d0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1a2e0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1a2f0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1a300 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1a310 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1a320 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1a330 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1a340 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1a350 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1a360 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1a370 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1a380 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1a390 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1a3a0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1a3b0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1a3c0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1a3d0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1a3e0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1a3f0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1a400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1a410 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1a420 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
1a430 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1a440 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1a450 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1a460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1a470 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1a480 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1a490 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1a4a0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1a4b0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1a4c0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1a4d0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1a4e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1a4f0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1a500 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1a510 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1a520 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1a530 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1a540 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1a550 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1a560 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1a570 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1a580 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1a590 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1a5a0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1a5b0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1a5c0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1a5d0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1a5e0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1a5f0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1a600 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1a610 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1a620 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1a630 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1a640 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1a650 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1a660 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1a670 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1a680 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1a690 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1a6a0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1a6b0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1a6c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1a6d0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1a6e0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1a6f0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1a700 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1a710 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1a720 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1a730 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1a740 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1a750 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1a760 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1a770 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1a780 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1a790 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1a7a0 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1a7b0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1a7c0 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1a7d0 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1a7e0 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1a7f0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1a800 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1a810 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1a820 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1a830 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1a840 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1a850 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1a860 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1a870 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1a880 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1a890 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1a8a0 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1a8b0 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1a8c0 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1a8d0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1a8e0 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1a8f0 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1a900 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1a910 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1a920 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1a930 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1a940 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1a950 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1a960 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1a970 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1a980 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1a990 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1a9a0 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1a9b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1a9c0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1a9d0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1a9e0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1a9f0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1aa00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1aa10 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1aa20 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1aa30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1aa40 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1aa50 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1aa60 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1aa70 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1aa80 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1aa90 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1aaa0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1aab0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1aac0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1aad0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1aae0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1aaf0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1ab00 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1ab10 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1ab20 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1ab30 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1ab40 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1ab50 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1ab60 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1ab70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1ab80 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1ab90 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1aba0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1abb0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1abc0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1abd0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1abe0 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72   N is the number
1abf0 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1ac00 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1ac10 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1ac20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
1ac30 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
1ac40 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1ac50 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a  he callback X..*
1ac60 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
1ac70 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
1ac80 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
1ac90 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
1aca0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
1acb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
1acc0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
1acd0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
1ace0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
1acf0 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
1ad00 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
1ad10 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
1ad20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ad30 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
1ad40 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
1ad50 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
1ad60 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
1ad70 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
1ad80 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
1ad90 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1ada0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1adb0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1adc0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1add0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1ade0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1adf0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1ae00 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1ae10 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1ae20 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1ae30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1ae40 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
1ae50 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1ae60 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1ae70 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1ae80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ae90 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1aea0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
1aeb0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
1aec0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1aed0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1aee0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1aef0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1af00 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1af10 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1af20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1af30 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1af40 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
1af50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1af60 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1af70 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1af80 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1af90 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1afa0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1afb0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1afc0 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
1afd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
1afe0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
1aff0 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
1b000 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
1b010 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
1b020 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1b030 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1b040 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1b050 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1b060 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1b070 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1b080 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1b090 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1b0a0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1b0b0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1b0c0 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1b0d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b0e0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1b0f0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1b100 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1b110 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1b120 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1b130 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1b140 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1b150 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1b160 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1b170 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1b180 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1b190 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1b1a0 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1b1b0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1b1c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1b1d0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1b1e0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1b1f0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1b200 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1b210 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1b220 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1b230 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1b240 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1b250 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1b260 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1b270 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1b280 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1b290 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1b2a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1b2b0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1b2c0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1b2d0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1b2e0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1b2f0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1b300 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1b310 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1b320 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1b330 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1b340 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1b350 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1b360 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1b370 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1b380 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1b390 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1b3a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1b3b0 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1b3c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1b3d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1b3e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1b3f0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1b400 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1b410 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1b420 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1b430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b440 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1b450 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1b460 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1b470 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1b480 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1b490 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1b4a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1b4b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b4c0 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1b4d0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1b4e0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1b4f0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1b500 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1b510 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1b520 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1b530 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1b540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b550 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1b560 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1b570 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1b580 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1b590 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1b5a0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1b5b0 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1b5c0 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1b5d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1b5e0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1b5f0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1b600 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1b610 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1b620 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  * and/or [SQLITE
1b630 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1b640 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  HE] flags:)^.**.
1b650 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1b660 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1b670 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1b680 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1b690 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1b6a0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1b6b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1b6c0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1b6d0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1b6e0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1b6f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1b700 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1b710 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
1b720 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1b730 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1b740 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1b750 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
1b760 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
1b770 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
1b780 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
1b790 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
1b7a0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
1b7b0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
1b7c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
1b7d0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
1b7e0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
1b7f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1b800 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1b810 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1b820 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
1b830 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1b840 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1b850 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1b860 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1b870 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
1b880 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
1b890 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1b8a0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1b8b0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1b8c0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1b8d0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1b8e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b8f0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1b900 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
1b910 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1b920 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1b930 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1b940 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1b950 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1b960 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1b970 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
1b980 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1b990 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
1b9a0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
1b9b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b9c0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1b9d0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a  EN_FULLMUTEX],.*
1b9e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  * [SQLITE_OPEN_S
1b9f0 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f  HAREDCACHE] and/
1ba00 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1ba10 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1ba20 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1ba30 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1ba40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
1ba50 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1ba60 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1ba70 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1ba80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ba90 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1baa0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1bab0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1bac0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1bad0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1bae0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1baf0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1bb00 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1bb10 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
1bb20 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1bb30 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1bb40 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
1bb50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1bb60 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
1bb70 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1bb80 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1bb90 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
1bba0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
1bbb0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
1bbc0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
1bbd0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1bbe0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1bbf0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1bc00 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1bc10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1bc20 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
1bc30 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
1bc40 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1bc50 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
1bc60 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1bc70 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1bc80 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
1bc90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1bca0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1bcb0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
1bcc0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1bcd0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
1bce0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1bcf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
1bd00 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
1bd10 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
1bd20 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
1bd30 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
1bd40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1bd50 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1bd60 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1bd70 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1bd80 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1bd90 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1bda0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1bdb0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1bdc0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1bdd0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1bde0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1bdf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1be00 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1be10 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1be20 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1be30 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1be40 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1be50 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1be60 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1be70 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1be80 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1be90 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1bea0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1beb0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1bec0 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1bed0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1bee0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1bef0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1bf00 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1bf10 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1bf20 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1bf30 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1bf40 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1bf50 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1bf60 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1bf70 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1bf80 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1bf90 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1bfa0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1bfb0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1bfc0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1bfd0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1bfe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1bff0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   closed..**.** ^
1c000 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1c010 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c020 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1c030 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1c040 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1c050 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1c060 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1c070 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1c080 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1c090 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c0a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1c0b0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1c0c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1c0d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c0e0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1c0f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1c100 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1c110 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
1c120 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
1c130 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
1c140 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
1c150 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1c160 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
1c170 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1c180 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
1c190 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
1c1a0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
1c1b0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
1c1c0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
1c1d0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
1c1e0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
1c1f0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
1c200 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
1c210 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
1c220 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
1c230 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1c240 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1c250 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20  en_v2()..*/.int 
1c260 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
1c270 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1c280 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1c290 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1c2a0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1c2b0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1c2c0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1c2d0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1c2e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1c2f0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
1c300 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
1c310 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1c320 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
1c330 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1c340 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1c350 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1c360 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1c370 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
1c380 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1c390 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1c3a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1c3b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1c3c0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
1c3d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1c3e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
1c3f0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
1c400 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
1c410 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1c420 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
1c430 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
1c440 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
1c450 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c460 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
1c470 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
1c480 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1c490 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
1c4a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1c4b0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
1c4c0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
1c4d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1c4e0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1c4f0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
1c500 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
1c510 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1c520 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1c530 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
1c540 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
1c550 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
1c560 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
1c570 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
1c580 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c590 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
1c5a0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
1c5b0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
1c5c0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1c5d0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
1c5e0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
1c5f0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
1c600 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
1c610 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
1c620 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1c630 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
1c640 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1c650 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
1c660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c670 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1c680 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1c690 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1c6a0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1c6b0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1c6c0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1c6d0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1c6e0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1c6f0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
1c700 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1c710 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1c720 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1c730 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1c740 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1c750 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1c760 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1c770 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1c780 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1c790 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1c7a0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1c7b0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1c7c0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1c7d0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1c7e0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1c7f0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
1c800 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
1c810 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1c820 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
1c830 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
1c840 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
1c850 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
1c860 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
1c870 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
1c880 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
1c890 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
1c8a0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
1c8b0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
1c8c0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
1c8d0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
1c8e0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
1c8f0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
1c900 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
1c910 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
1c920 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
1c930 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
1c940 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
1c950 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
1c960 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
1c970 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
1c980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c990 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
1c9a0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1c9b0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
1c9c0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1c9d0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
1c9e0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
1c9f0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
1ca00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
1ca10 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
1ca20 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
1ca30 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
1ca40 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
1ca50 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
1ca60 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
1ca70 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
1ca80 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
1ca90 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
1caa0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
1cab0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
1cac0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
1cad0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1cae0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
1caf0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
1cb00 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
1cb10 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
1cb20 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
1cb30 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1cb40 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1cb50 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1cb60 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1cb70 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1cb80 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1cb90 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1cba0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1cbb0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1cbc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cbd0 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1cbe0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
1cbf0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1cc00 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1cc10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1cc20 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1cc30 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1cc40 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1cc50 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1cc60 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1cc70 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1cc80 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1cc90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cca0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1ccb0 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1ccc0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1ccd0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1cce0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1ccf0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1cd00 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1cd10 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1cd20 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1cd30 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1cd40 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1cd50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1cd60 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1cd70 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1cd80 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1cd90 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1cda0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1cdb0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1cdc0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1cdd0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1cde0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1cdf0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1ce00 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1ce10 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1ce20 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1ce30 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1ce40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1ce50 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1ce60 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1ce70 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1ce80 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1ce90 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1cea0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1ceb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1cec0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1ced0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1cee0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1cef0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1cf00 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1cf10 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1cf20 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1cf30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1cf40 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1cf50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cf60 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1cf70 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
1cf80 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1cf90 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1cfa0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1cfb0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1cfc0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1cfd0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1cfe0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1cff0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1d000 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d010 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1d020 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1d030 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1d040 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1d050 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1d060 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1d070 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1d080 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1d090 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1d0a0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1d0b0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1d0c0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1d0d0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1d0e0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
1d0f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
1d100 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
1d110 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
1d120 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
1d130 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
1d140 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
1d150 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
1d160 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
1d170 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
1d180 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
1d190 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
1d1a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
1d1b0 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
1d1c0 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
1d1d0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
1d1e0 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
1d1f0 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
1d200 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1d210 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1d220 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
1d230 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
1d240 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1d250 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1d260 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1d270 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1d280 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1d290 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
1d2a0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
1d2b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1d2c0 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
1d2d0 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
1d2e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1d2f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1d300 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
1d310 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
1d320 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
1d330 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
1d340 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
1d350 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
1d360 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
1d370 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
1d380 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
1d390 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
1d3a0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
1d3b0 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
1d3c0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1d3d0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1d3e0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1d3f0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1d400 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1d410 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1d420 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1d430 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1d440 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1d450 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1d460 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1d470 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1d480 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
1d490 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1d4a0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1d4b0 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1d4c0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1d4d0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1d4e0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1d4f0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1d500 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1d510 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1d520 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1d530 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1d540 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1d550 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1d560 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1d570 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1d580 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1d590 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1d5a0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1d5b0 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1d5c0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1d5d0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1d5e0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1d5f0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1d600 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1d610 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1d620 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1d630 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1d640 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1d650 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1d660 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1d670 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1d680 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1d690 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1d6a0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1d6b0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1d6c0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1d6d0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1d6e0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1d6f0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1d700 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1d710 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1d720 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1d730 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1d740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d750 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1d760 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1d770 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1d780 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1d790 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1d7a0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1d7b0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1d7c0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1d7d0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1d7e0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1d7f0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1d800 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1d810 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1d820 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1d830 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1d840 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1d850 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1d860 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1d870 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1d880 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1d890 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1d8a0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1d8b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1d8c0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d8d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1d8e0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1d8f0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1d900 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
1d910 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d920 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
1d930 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
1d940 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d950 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
1d960 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
1d970 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
1d980 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d990 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
1d9a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d9b0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d9c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
1d9d0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
1d9e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
1d9f0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1da00 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
1da10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1da20 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1da30 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
1da40 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
1da50 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
1da60 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1da70 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1da80 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1da90 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1daa0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
1dab0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
1dac0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
1dad0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1dae0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1daf0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
1db00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1db10 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1db20 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1db30 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1db40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1db50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1db60 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
1db70 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1db80 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
1db90 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
1dba0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
1dbb0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
1dbc0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
1dbd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
1dbe0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
1dbf0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
1dc00 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
1dc10 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
1dc20 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
1dc30 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
1dc40 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
1dc50 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1dc60 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1dc70 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1dc80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1dc90 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1dca0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1dcb0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1dcc0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
1dcd0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
1dce0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1dcf0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
1dd00 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
1dd10 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
1dd20 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1dd30 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1dd40 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
1dd50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1dd60 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
1dd70 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
1dd80 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
1dd90 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
1dda0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
1ddb0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1ddc0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1ddd0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
1dde0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1ddf0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
1de00 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
1de10 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1de20 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ment.)^.**.** ^(
1de30 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1de40 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
1de50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1de60 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1de70 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
1de80 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
1de90 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1dea0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1deb0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1dec0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1ded0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1dee0 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1def0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1df00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1df10 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1df20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1df30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1df40 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1df50 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1df60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1df70 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1df80 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1df90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1dfa0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1dfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1dfc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dfd0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1dfe0 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1dff0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1e000 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1e010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e020 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1e030 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1e040 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1e050 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1e060 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1e070 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1e080 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
1e090 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1e0a0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1e0b0 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
1e0c0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1e0d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1e0e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1e0f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1e100 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
1e110 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
1e120 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
1e130 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
1e140 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
1e150 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
1e160 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
1e170 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1e180 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1e190 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
1e1a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e1b0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
1e1c0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
1e1d0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1e1e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1e1f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1e200 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
1e210 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1e220 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
1e230 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
1e240 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
1e250 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
1e260 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1e270 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1e280 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1e290 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1e2a0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1e2b0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1e2c0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1e2d0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1e2e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1e2f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1e300 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1e310 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1e320 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e330 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1e340 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1e350 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
1e360 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1e370 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1e380 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1e390 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1e3a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1e3b0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
1e3c0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1e3d0 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1e3e0 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
1e3f0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1e400 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
1e410 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1e420 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1e430 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1e440 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1e450 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1e460 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1e470 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1e480 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1e490 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1e4a0 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1e4b0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1e4c0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1e4d0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1e4e0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1e4f0 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1e500 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1e510 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1e520 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1e530 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1e540 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1e550 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1e560 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1e570 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1e580 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1e590 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1e5a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  es..**.** ^If pz
1e5b0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1e5c0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1e5d0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1e5e0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1e5f0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
1e600 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1e610 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1e620 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1e630 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
1e640 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
1e650 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1e660 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1e670 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1e680 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
1e690 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1e6a0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
1e6b0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1e6c0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1e6d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e6e0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1e6f0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1e700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1e710 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
1e720 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1e730 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1e740 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
1e750 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1e760 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1e770 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
1e780 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
1e790 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1e7a0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1e7b0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
1e7c0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1e7d0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1e7e0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1e7f0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1e800 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1e810 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1e820 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1e830 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1e840 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
1e850 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
1e860 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
1e870 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
1e880 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
1e890 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1e8a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
1e8b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
1e8c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1e8d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1e8e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1e8f0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
1e900 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e910 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
1e920 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
1e930 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
1e940 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
1e950 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
1e960 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
1e970 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1e980 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
1e990 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
1e9a0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
1e9b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1e9c0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1e9d0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1e9e0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1e9f0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1ea00 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1ea10 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1ea20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
1ea30 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
1ea40 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1ea50 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1ea60 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1ea70 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
1ea80 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
1ea90 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1eaa0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
1eab0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1eac0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1ead0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1eae0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1eaf0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1eb00 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1eb10 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1eb20 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1eb30 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1eb40 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1eb50 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1eb60 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1eb70 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
1eb80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1eb90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1eba0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1ebb0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1ebc0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1ebd0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1ebe0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
1ebf0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1ec00 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
1ec10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1ec20 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
1ec30 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
1ec40 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
1ec50 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
1ec60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
1ec70 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
1ec80 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
1ec90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1eca0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
1ecb0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
1ecc0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
1ecd0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
1ece0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
1ecf0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
1ed00 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1ed10 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
1ed20 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1ed30 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1ed40 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
1ed50 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
1ed60 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
1ed70 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
1ed80 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
1ed90 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
1eda0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
1edb0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
1edc0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
1edd0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
1ede0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
1edf0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
1ee00 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
1ee10 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
1ee20 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
1ee30 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
1ee40 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
1ee50 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
1ee60 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
1ee70 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
1ee80 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
1ee90 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
1eea0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
1eeb0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
1eec0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
1eed0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
1eee0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
1eef0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
1ef00 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
1ef10 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
1ef20 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1ef30 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
1ef40 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
1ef50 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
1ef60 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
1ef70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
1ef80 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
1ef90 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
1efa0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
1efb0 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d  NABLE_STAT2] com
1efc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1efd0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
1efe0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
1eff0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
1f000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1f010 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f020 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f030 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f040 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f050 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f060 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1f070 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f080 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f090 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f0a0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1f0b0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1f0c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1f0d0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1f0e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1f0f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f100 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1f110 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1f120 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1f130 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1f140 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f150 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1f160 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1f170 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1f180 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1f190 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1f1a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1f1b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1f1c0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1f1d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1f1e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1f1f0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1f200 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1f210 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1f220 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1f230 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f240 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1f250 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1f260 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1f270 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1f280 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1f290 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1f2a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f2b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1f2c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f2d0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1f2e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1f2f0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1f300 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1f310 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1f320 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1f330 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1f340 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1f350 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1f360 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1f370 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1f380 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1f390 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1f3a0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1f3b0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1f3c0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1f3d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f3e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1f3f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f400 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f410 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f420 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f430 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f440 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1f450 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f460 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f470 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1f480 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1f490 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1f4a0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1f4b0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1f4c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f4d0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1f4e0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1f4f0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1f500 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1f510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f520 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1f530 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
1f540 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
1f550 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1f560 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
1f570 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
1f580 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
1f590 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
1f5a0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
1f5b0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
1f5c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
1f5d0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
1f5e0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1f5f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f600 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f610 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
1f620 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1f630 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
1f640 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1f650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1f660 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1f670 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
1f680 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
1f690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f6a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
1f6b0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
1f6c0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
1f6d0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
1f6e0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
1f6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f700 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
1f710 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
1f720 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
1f730 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1f740 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
1f750 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
1f760 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1f770 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
1f780 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
1f790 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
1f7a0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
1f7b0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
1f7c0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
1f7d0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
1f7e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
1f7f0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
1f800 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
1f810 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
1f820 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
1f830 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
1f840 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
1f850 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
1f860 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
1f870 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
1f880 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f890 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
1f8a0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
1f8b0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
1f8c0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
1f8d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1f8e0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
1f8f0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
1f900 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
1f910 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
1f920 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
1f930 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
1f940 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
1f950 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
1f960 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
1f970 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
1f980 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
1f990 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
1f9a0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
1f9b0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
1f9c0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
1f9d0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
1f9e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
1f9f0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
1fa00 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
1fa10 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
1fa20 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
1fa30 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
1fa40 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
1fa50 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
1fa60 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
1fa70 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
1fa80 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
1fa90 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
1faa0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
1fab0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
1fac0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
1fad0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
1fae0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
1faf0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
1fb00 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
1fb10 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
1fb20 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
1fb30 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
1fb40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
1fb50 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
1fb60 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
1fb70 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
1fb80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1fb90 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
1fba0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
1fbb0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
1fbc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1fbd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1fbe0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
1fbf0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
1fc00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
1fc10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1fc20 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
1fc30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1fc40 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1fc50 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
1fc60 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
1fc70 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
1fc80 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
1fc90 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
1fca0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
1fcb0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
1fcc0 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
1fcd0 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
1fce0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
1fcf0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
1fd00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
1fd10 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
1fd20 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
1fd30 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
1fd40 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
1fd50 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
1fd60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fd70 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
1fd80 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
1fd90 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
1fda0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
1fdb0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
1fdc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1fdd0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
1fde0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
1fdf0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
1fe00 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
1fe10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1fe20 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
1fe30 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1fe40 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
1fe50 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
1fe60 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1fe70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
1fe80 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
1fe90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1fea0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
1feb0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
1fec0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
1fed0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
1fee0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
1fef0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
1ff00 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
1ff10 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
1ff20 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ff30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1ff40 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
1ff50 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
1ff60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ff70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
1ff80 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1ff90 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
1ffa0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
1ffb0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
1ffc0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
1ffd0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
1ffe0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
1fff0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
20000 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
20010 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
20020 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
20030 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
20040 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
20050 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
20060 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
20070 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
20080 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
20090 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
200a0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
200b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
200c0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
200d0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
200e0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
200f0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
20100 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
20110 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
20120 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
20130 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
20140 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
20150 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
20160 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
20170 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
20180 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20190 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
201a0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
201b0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
201c0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
201d0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
201e0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
201f0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
20200 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
20210 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
20220 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
20230 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
20240 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
20250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20260 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
20270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
20280 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
20290 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
202a0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
202b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
202c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
202d0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
202e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
202f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20300 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
20310 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
20320 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
20330 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
20340 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
20350 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
20360 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
20370 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20380 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
20390 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
203a0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
203b0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
203c0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
203d0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
203e0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
203f0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
20400 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
20410 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
20420 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
20430 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
20440 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
20450 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
20460 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
20470 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
20480 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
20490 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
204a0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
204b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
204c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
204d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
204e0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
204f0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
20500 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20510 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
20520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
20530 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
20540 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
20550 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
20560 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
20570 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
20580 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
20590 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
205a0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
205b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
205c0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
205d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
205e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
205f0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
20600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
20610 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
20620 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
20630 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
20640 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20650 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
20660 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
20670 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
20680 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
20690 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
206a0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
206b0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
206c0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
206d0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
206e0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
206f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
20700 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
20710 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
20720 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
20730 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
20740 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
20750 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
20760 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
20770 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
20780 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
20790 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
207a0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
207b0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
207c0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
207d0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
207e0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
207f0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
20800 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
20810 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
20820 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
20830 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
20840 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
20850 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
20860 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
20870 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
20880 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
20890 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
208a0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
208b0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
208c0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
208d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
208e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
208f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20900 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
20910 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
20920 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
20930 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
20940 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
20950 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20960 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
20970 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
20980 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
20990 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
209a0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
209b0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
209c0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
209d0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
209e0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
209f0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
20a00 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
20a10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
20a20 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
20a30 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
20a40 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
20a50 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
20a60 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
20a70 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
20a80 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
20a90 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
20aa0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
20ab0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
20ac0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
20ad0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
20ae0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
20af0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
20b00 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
20b10 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
20b20 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
20b30 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
20b40 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
20b50 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
20b60 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20b70 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
20b80 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
20b90 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
20ba0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
20bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
20bc0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
20bd0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
20be0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
20bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
20c00 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
20c10 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
20c20 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
20c30 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
20c40 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
20c50 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
20c60 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
20c70 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
20c80 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
20c90 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
20ca0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
20cb0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
20cc0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
20cd0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
20ce0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
20cf0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
20d00 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
20d10 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
20d20 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
20d30 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
20d40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
20d50 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
20d60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20d70 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
20d80 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
20d90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
20da0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
20db0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
20dc0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
20dd0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
20de0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
20df0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
20e00 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
20e10 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
20e20 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
20e30 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
20e40 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
20e50 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
20e60 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
20e70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
20e80 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
20e90 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
20ea0 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
20eb0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
20ec0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
20ed0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
20ee0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
20ef0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
20f00 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
20f10 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
20f20 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
20f30 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
20f40 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
20f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
20f60 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
20f70 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
20f80 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
20f90 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
20fa0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
20fb0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
20fc0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
20fd0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
20fe0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
20ff0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
21000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21010 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
21020 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
21030 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
21040 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
21050 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
21060 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
21070 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
21080 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
21090 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
210a0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
210b0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
210c0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
210d0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
210e0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
210f0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
21100 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
21110 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
21120 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
21130 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
21140 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
21150 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
21160 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
21170 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
21180 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
21190 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
211a0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
211b0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
211c0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
211d0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
211e0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
211f0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
21200 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
21210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21220 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
21230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
21240 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
21250 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
21260 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
21270 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
21280 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21290 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
212a0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
212b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
212c0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
212d0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
212e0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
212f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21300 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
21310 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
21320 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
21330 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
21340 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
21350 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
21360 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
21370 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
21380 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
21390 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
213a0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
213b0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
213c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
213d0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
213e0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
213f0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
21400 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
21410 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
21420 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
21430 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
21440 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
21450 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
21460 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
21470 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
21480 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
21490 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
214a0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
214b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
214c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
214d0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
214e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
214f0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
21500 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
21510 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21520 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
21530 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
21540 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21550 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
21560 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
21570 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
21580 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
21590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
215a0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
215b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
215c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
215d0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
215e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
215f0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
21600 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
21610 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
21620 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
21630 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
21640 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21650 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
21660 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21670 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
21680 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
21690 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
216a0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
216b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
216c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
216d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
216e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
216f0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
21700 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
21710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
21720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21730 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
21740 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
21750 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
21760 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
21770 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
21780 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
21790 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
217a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
217b0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
217c0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
217d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
217e0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
217f0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
21800 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
21810 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
21820 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
21830 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
21840 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
21850 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
21860 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
21870 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
21880 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
21890 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
218a0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
218b0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
218c0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
218d0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
218e0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
218f0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
21900 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
21910 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
21920 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
21930 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
21940 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
21950 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
21960 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
21970 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
21980 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
21990 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
219a0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
219b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
219c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
219d0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
219e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
219f0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
21a00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
21a10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21a20 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
21a30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
21a40 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
21a50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
21a60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
21a70 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
21a80 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
21a90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
21aa0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
21ab0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
21ac0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
21ad0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
21ae0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
21af0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21b00 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
21b10 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
21b20 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
21b30 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
21b40 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
21b50 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
21b60 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
21b70 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
21b80 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
21b90 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
21ba0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
21bb0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
21bc0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
21bd0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
21be0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
21bf0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
21c00 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
21c10 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
21c20 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
21c30 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
21c40 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
21c50 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
21c60 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
21c70 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
21c80 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
21c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
21ca0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
21cb0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
21cc0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
21cd0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
21ce0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
21cf0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
21d00 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
21d10 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
21d20 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
21d30 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
21d40 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
21d50 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
21d60 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
21d70 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
21d80 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
21d90 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
21da0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
21db0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21dc0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21dd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
21de0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
21df0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21e00 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
21e10 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21e20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21e30 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
21e40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21e50 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21e60 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
21e70 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
21e80 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
21e90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21ea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21eb0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
21ec0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
21ed0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
21ee0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
21ef0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
21f00 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
21f10 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
21f20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
21f30 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
21f40 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
21f50 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
21f60 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
21f70 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
21f80 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
21f90 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
21fa0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
21fb0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
21fc0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
21fd0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
21fe0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
21ff0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
22000 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
22010 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
22020 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
22030 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
22040 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22050 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
22060 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
22070 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
22080 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
22090 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
220a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
220b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
220c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
220d0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
220e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
220f0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
22100 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
22110 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
22120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22130 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
22140 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
22150 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
22160 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
22170 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
22180 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
22190 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
221a0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
221b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
221c0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
221d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
221e0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
221f0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
22200 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
22210 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
22220 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22230 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
22240 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
22250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22260 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
22270 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
22280 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
22290 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
222a0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
222b0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
222c0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
222d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
222e0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
222f0 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
22300 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
22310 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
22320 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
22330 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
22340 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
22350 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
22360 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
22370 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
22380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
22390 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
223a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
223b0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
223c0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
223d0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
223e0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
223f0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
22400 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
22410 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
22420 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
22430 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
22440 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
22450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22460 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
22470 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
22480 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
22490 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
224a0 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
224b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
224c0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
224d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
224e0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
224f0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
22500 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22510 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
22520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
22530 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
22540 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
22550 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
22560 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22570 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
22580 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
22590 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
225a0 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
225b0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
225c0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
225d0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
225e0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
225f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
22600 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
22610 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
22620 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
22630 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
22640 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22650 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
22660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22670 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
22680 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
22690 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
226a0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
226b0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
226c0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
226d0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
226e0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
226f0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
22700 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
22710 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
22720 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
22730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
22740 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
22750 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
22760 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
22770 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
22780 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
22790 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
227a0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
227b0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
227c0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
227d0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
227e0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
227f0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
22800 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
22810 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
22820 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
22830 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22840 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
22850 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
22860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
22870 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
22880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22890 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
228a0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
228b0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
228c0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
228d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
228e0 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
228f0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
22900 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
22910 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
22920 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
22930 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
22940 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
22950 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
22960 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
22970 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
22980 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
22990 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
229a0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
229b0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
229c0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
229d0 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
229e0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
229f0 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
22a00 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
22a10 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
22a20 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
22a30 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
22a40 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
22a50 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
22a60 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
22a70 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
22a80 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
22a90 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
22aa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
22ab0 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
22ac0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
22ad0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
22ae0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
22af0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
22b00 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
22b10 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
22b20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
22b30 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
22b40 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
22b50 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
22b60 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
22b70 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
22b80 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
22b90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22ba0 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
22bb0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
22bc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22bd0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
22be0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
22bf0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
22c00 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
22c10 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
22c20 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
22c30 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
22c40 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
22c50 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
22c60 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
22c70 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
22c80 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
22c90 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
22ca0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
22cb0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
22cc0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
22cd0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
22ce0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
22cf0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
22d00 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
22d10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
22d20 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
22d30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
22d40 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
22d50 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
22d60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
22d70 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
22d80 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
22d90 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
22da0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
22db0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
22dc0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
22dd0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
22de0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
22df0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
22e00 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
22e10 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
22e20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
22e30 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
22e40 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
22e50 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
22e60 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
22e70 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
22e80 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
22e90 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
22ea0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
22eb0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
22ec0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
22ed0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
22ee0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
22ef0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
22f00 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
22f10 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
22f20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
22f30 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
22f40 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
22f50 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
22f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22f70 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
22f80 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
22f90 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
22fa0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
22fb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
22fc0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
22fd0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
22fe0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
22ff0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
23000 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
23010 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
23020 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
23030 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23040 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
23050 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
23060 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
23070 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
23080 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
23090 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
230a0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
230b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
230c0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
230d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
230e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
230f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
23100 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
23110 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
23120 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
23130 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23140 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
23160 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
23170 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
23180 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23190 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
231a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
231b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
231c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
231d0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
231e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
231f0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
23200 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
23210 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
23220 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
23230 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
23240 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
23250 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23260 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
23270 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
23280 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
23290 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
232a0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
232b0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
232c0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
232d0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
232e0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
232f0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
23300 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
23310 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
23320 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
23330 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
23340 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
23350 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
23360 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
23370 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
23380 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
23390 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
233a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
233b0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
233c0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
233d0 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
233e0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
233f0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
23400 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
23410 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
23420 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
23430 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
23440 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
23450 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
23460 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
23470 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
23480 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
23490 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
234a0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
234b0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
234c0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
234d0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
234e0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
234f0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
23500 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
23510 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
23520 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
23530 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
23540 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
23550 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
23560 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
23570 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
23580 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
23590 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
235a0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
235b0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
235c0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
235d0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
235e0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
235f0 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
23600 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
23610 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
23620 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
23630 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
23640 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
23650 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
23660 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
23670 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
23680 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
23690 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
236a0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
236b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
236c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
236d0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
236e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
236f0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
23700 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
23710 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
23720 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
23730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23740 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
23750 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
23760 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
23770 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
23780 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
23790 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
237a0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
237b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
237c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
237d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
237e0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
237f0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
23800 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
23810 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
23820 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
23830 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
23840 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
23850 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
23860 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
23870 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
23880 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
23890 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
238a0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
238b0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
238c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
238d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
238e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
238f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
23900 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
23910 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
23920 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
23930 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
23940 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
23950 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
23960 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
23970 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
23980 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
23990 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
239a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
239b0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
239c0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
239d0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
239e0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
239f0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
23a00 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
23a10 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
23a20 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
23a30 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
23a40 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
23a50 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
23a60 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
23a70 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
23a80 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
23a90 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
23aa0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
23ab0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23ac0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
23ad0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
23ae0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
23af0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
23b00 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
23b10 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
23b20 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
23b30 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
23b40 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
23b50 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
23b60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
23b70 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
23b80 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
23b90 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
23ba0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
23bb0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
23bc0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
23bd0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
23be0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
23bf0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
23c00 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
23c10 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
23c20 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
23c30 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
23c40 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
23c50 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
23c60 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
23c70 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
23c80 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
23c90 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
23ca0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
23cb0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
23cc0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
23cd0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
23ce0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
23cf0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
23d00 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
23d10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23d20 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
23d30 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
23d40 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
23d50 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
23d60 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
23d70 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
23d80 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
23d90 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
23da0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
23db0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
23dc0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
23dd0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
23de0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
23df0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
23e00 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
23e10 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
23e20 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
23e30 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
23e40 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
23e50 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
23e60 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
23e70 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
23e80 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
23e90 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
23ea0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
23eb0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
23ec0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
23ed0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
23ee0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
23ef0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
23f00 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
23f10 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
23f20 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
23f30 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
23f40 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
23f50 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
23f60 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
23f70 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
23f80 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
23f90 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
23fa0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
23fb0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
23fc0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
23fd0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
23fe0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
23ff0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
24000 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
24010 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
24020 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
24030 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
24040 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
24050 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
24060 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
24070 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
24080 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
24090 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
240a0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
240b0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
240c0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
240d0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
240e0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
240f0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
24100 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
24110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24120 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
24130 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
24140 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
24150 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
24160 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
24170 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
24180 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
24190 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
241a0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
241b0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
241c0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
241d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
241e0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
241f0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
24200 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
24210 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
24220 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
24230 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
24240 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
24250 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
24260 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
24270 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24280 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
24290 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
242a0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
242b0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
242c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
242d0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
242e0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
242f0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
24300 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
24310 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
24320 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24330 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
24340 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
24350 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
24360 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
24370 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
24380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
24390 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
243a0 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
243b0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
243c0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
243d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
243e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
243f0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
24400 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
24410 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
24420 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
24430 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
24440 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
24450 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
24460 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
24470 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
24480 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
24490 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
244a0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
244b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
244c0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
244d0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
244e0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
244f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
24500 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
24510 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
24520 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
24530 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
24540 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
24550 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
24560 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
24570 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
24580 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
24590 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
245a0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
245b0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
245c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
245d0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
245e0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
245f0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
24600 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24610 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
24620 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
24630 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
24640 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
24650 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
24660 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
24670 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
24680 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
24690 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
246a0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
246b0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
246c0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
246d0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
246e0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
246f0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
24700 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
24710 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
24720 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24730 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
24740 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
24750 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
24760 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
24770 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
24780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24790 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
247a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
247b0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
247c0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
247d0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
247e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
247f0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
24800 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
24810 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
24820 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
24830 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
24840 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
24850 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
24860 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
24870 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
24880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
24890 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
248a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
248b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
248c0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
248d0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
248e0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
248f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24900 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
24910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24920 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
24930 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
24940 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
24950 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
24960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
24970 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
24980 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
24990 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
249a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
249b0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
249c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
249d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
249e0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
249f0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
24a00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
24a10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
24a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
24a30 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
24a40 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
24a50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24a60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24a70 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
24a80 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
24a90 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
24aa0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
24ab0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
24ac0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
24ad0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
24ae0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
24af0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
24b00 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
24b10 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
24b20 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
24b30 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
24b40 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
24b50 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
24b60 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
24b70 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
24b80 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
24b90 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
24ba0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
24bb0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
24bc0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
24bd0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
24be0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
24bf0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
24c00 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
24c10 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
24c20 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
24c30 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
24c40 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
24c50 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
24c60 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
24c70 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
24c80 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
24c90 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
24ca0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
24cb0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
24cc0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
24cd0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
24ce0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
24cf0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
24d00 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
24d10 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
24d20 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
24d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
24d40 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
24d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
24d60 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
24d70 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
24d80 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
24d90 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
24da0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
24db0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
24dc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
24dd0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
24de0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
24df0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
24e00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
24e10 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
24e20 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
24e30 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
24e40 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
24e50 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
24e60 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
24e70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
24e80 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
24e90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24ea0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
24eb0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
24ec0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
24ed0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
24ee0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
24ef0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24f00 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
24f10 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
24f20 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
24f30 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
24f40 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
24f50 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
24f60 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
24f70 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
24f80 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
24f90 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
24fa0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
24fb0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
24fc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
24fd0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
24fe0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
24ff0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
25000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
25010 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
25020 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
25030 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
25040 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
25050 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
25060 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
25070 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
25080 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
25090 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
250a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
250b0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
250c0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
250d0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
250e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
250f0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
25100 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
25110 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
25120 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25130 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
25140 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
25150 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
25160 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
25170 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
25180 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
25190 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
251a0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
251b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
251c0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
251d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
251e0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
251f0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
25200 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
25210 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
25220 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
25230 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25240 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
25250 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
25260 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
25270 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
25280 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
25290 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
252a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
252b0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
252c0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
252d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
252e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
252f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
25300 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
25310 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
25320 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
25330 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
25340 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
25350 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
25360 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
25370 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
25380 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
25390 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
253a0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
253b0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
253c0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
253d0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
253e0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
253f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
25400 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
25410 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
25420 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
25430 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
25440 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
25450 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
25460 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
25470 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
25480 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
25490 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
254a0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
254b0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
254c0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
254d0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
254e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
254f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25500 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
25510 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
25520 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
25530 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
25540 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
25550 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
25560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25570 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
25580 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
25590 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
255a0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
255b0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
255c0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
255d0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
255e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
255f0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
25600 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
25610 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
25620 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
25630 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
25640 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
25650 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
25660 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
25670 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
25680 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
25690 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
256a0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
256b0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
256c0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
256d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
256e0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
256f0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
25700 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
25710 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
25720 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
25730 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
25740 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
25750 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
25760 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
25770 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
25780 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
25790 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
257a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
257b0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
257c0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
257d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
257e0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
257f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
25800 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
25810 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
25820 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
25830 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
25840 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
25850 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
25860 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
25870 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
25880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25890 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
258a0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
258b0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
258c0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
258d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
258e0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
258f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25900 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
25910 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
25920 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
25930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25940 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
25950 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
25960 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
25970 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
25980 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
25990 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
259a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
259b0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
259c0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
259d0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
259e0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
259f0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
25a00 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
25a10 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
25a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25a30 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
25a40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
25a50 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
25a60 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
25a70 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
25a80 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
25a90 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
25aa0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
25ab0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
25ac0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
25ad0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25ae0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
25af0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
25b00 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
25b10 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54   terminated.  ^T
25b20 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
25b30 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
25b40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
25b50 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
25b60 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
25b70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
25b80 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
25b90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
25ba0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
25bb0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
25bc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25bd0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
25be0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
25bf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25c00 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
25c10 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
25c20 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
25c30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
25c40 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
25c50 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
25c60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25c70 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
25c80 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
25c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25ca0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
25cb0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
25cc0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
25cd0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
25ce0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25cf0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
25d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
25d10 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
25d20 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
25d30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
25d40 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
25d50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25d60 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
25d70 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
25d80 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
25d90 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
25da0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
25db0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
25dc0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
25dd0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
25de0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
25df0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
25e00 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
25e10 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
25e20 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
25e30 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
25e40 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
25e50 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
25e60 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
25e70 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
25e80 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
25e90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
25ea0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
25eb0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
25ec0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
25ed0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
25ee0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
25ef0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
25f00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
25f10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
25f20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
25f30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
25f40 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
25f50 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
25f60 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
25f70 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
25f80 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
25f90 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
25fa0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
25fb0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
25fc0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
25fd0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
25fe0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
25ff0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
26000 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
26010 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
26020 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
26030 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
26040 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
26050 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
26060 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
26070 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
26080 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
26090 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
260a0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
260b0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
260c0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
260d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
260e0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
260f0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
26100 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
26110 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
26120 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
26130 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
26140 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
26150 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
26160 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
26170 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
26180 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
26190 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
261a0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
261b0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
261c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
261d0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
261e0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
261f0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
26200 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
26210 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
26220 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
26230 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
26240 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
26250 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
26260 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
26270 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
26280 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
26290 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
262a0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
262b0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
262c0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
262d0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
262e0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
262f0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
26300 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
26310 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
26320 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
26330 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
26340 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
26350 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
26360 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
26370 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
26380 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
26390 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
263a0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
263b0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
263c0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
263d0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
263e0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
263f0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
26400 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
26410 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
26420 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
26430 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
26440 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
26450 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
26460 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
26470 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
26480 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
26490 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
264a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
264b0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
264c0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
264d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
264e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
264f0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
26500 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
26510 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
26520 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
26530 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
26540 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
26550 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
26560 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
26570 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
26580 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
26590 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
265a0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
265b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
265c0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
265d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
265e0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
265f0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
26600 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
26610 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
26620 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
26630 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
26640 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
26650 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
26660 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
26670 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
26680 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
26690 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
266a0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
266b0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
266c0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
266d0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
266e0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
266f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26700 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
26710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26720 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
26730 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
26740 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26750 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
26760 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
26770 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
26780 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
26790 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
267a0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
267b0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
267c0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
267d0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
267e0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
267f0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
26800 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
26810 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
26820 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
26830 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
26840 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
26850 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
26860 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
26870 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
26880 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
26890 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
268a0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
268b0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
268c0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
268d0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
268e0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
268f0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
26900 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
26910 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
26920 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
26930 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
26940 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
26950 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
26960 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
26970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26980 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
26990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
269a0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
269b0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
269c0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
269d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
269e0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
269f0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
26a00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
26a10 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
26a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26a30 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
26a40 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
26a50 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
26a60 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
26a70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
26a80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
26a90 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
26aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26ab0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
26ac0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
26ad0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
26ae0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
26af0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
26b00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
26b10 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
26b20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
26b30 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
26b40 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
26b50 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
26b60 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
26b70 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
26b80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26b90 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
26ba0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
26bb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
26bc0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
26bd0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
26be0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
26bf0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
26c00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26c10 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
26c20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
26c30 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
26c40 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
26c50 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
26c60 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
26c70 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
26c80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26c90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
26ca0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
26cb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
26cc0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
26cd0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
26ce0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
26cf0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
26d00 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
26d10 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
26d20 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
26d30 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
26d40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
26d50 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
26d60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26d70 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
26d80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
26d90 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
26da0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
26db0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
26dc0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
26dd0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
26de0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
26df0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
26e00 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
26e10 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
26e20 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
26e30 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
26e40 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
26e50 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
26e60 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
26e70 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
26e80 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
26e90 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
26ea0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
26eb0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
26ec0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
26ed0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26ee0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
26ef0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
26f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26f10 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
26f20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
26f40 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
26f50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26f60 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
26f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
26f80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26f90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
26fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
26fb0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
26fc0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
26fd0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
26fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
26ff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27000 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
27010 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
27020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27030 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
27040 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
27050 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27060 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
27070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27080 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
27090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
270a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
270b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
270c0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
270d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
270e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
270f0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
27100 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
27110 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
27120 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
27130 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27140 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
27150 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
27160 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
27170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
27190 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
271a0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
271b0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
271c0 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20  no errors or.** 
271d0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
271e0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
271f0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
27200 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
27210 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
27220 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
27230 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27240 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
27250 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
27260 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
27270 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
27280 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
27290 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
272a0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
272b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
272c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
272d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
272e0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
272f0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
27300 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
27310 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
27320 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27330 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
27340 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
27350 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
27360 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
27370 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
27380 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
27390 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
273a0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
273b0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
273c0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
273d0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
273e0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
273f0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
27400 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
27410 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27420 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
27430 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
27440 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
27450 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27460 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
27470 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
27480 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
27490 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
274a0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
274b0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
274c0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
274d0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
274e0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
274f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27500 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
27510 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
27520 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
27530 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
27540 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
27550 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
27560 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
27570 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
27580 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
27590 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
275a0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
275b0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
275c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
275d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
275e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
275f0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
27600 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27610 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
27620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
27630 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
27640 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
27650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27660 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
27670 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
27680 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
27690 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
276a0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
276b0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
276c0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
276d0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
276e0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
276f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27700 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
27710 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
27720 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
27730 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
27740 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
27750 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
27760 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
27770 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
27780 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
27790 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
277a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
277b0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
277c0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
277d0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
277e0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
277f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
27800 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
27810 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
27820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27830 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
27840 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
27850 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
27860 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
27870 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
27880 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
27890 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
278a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
278b0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
278c0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
278d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
278e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
278f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
27900 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
27910 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
27920 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
27930 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
27940 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
27950 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
27960 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
27970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
27980 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
27990 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
279a0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
279b0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
279c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
279d0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
279e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
279f0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
27a00 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
27a10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27a20 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
27a30 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
27a40 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
27a50 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
27a60 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
27a70 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
27a80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
27a90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27aa0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
27ab0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
27ac0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27ad0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
27ae0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
27af0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
27b00 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
27b10 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
27b20 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
27b30 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
27b40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
27b50 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
27b60 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
27b70 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
27b80 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
27b90 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
27ba0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
27bb0 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
27bc0 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
27bd0 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
27be0 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
27bf0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 74  ted for.** the t
27c00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
27c10 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
27c20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
27c30 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
27c40 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
27c50 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
27c60 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
27c70 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
27c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
27c90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
27ca0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
27cb0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
27cc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27cd0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
27ce0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
27cf0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
27d00 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
27d10 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
27d20 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
27d30 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
27d40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
27d50 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27d60 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
27d70 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
27d80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27d90 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
27da0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
27db0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
27dc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
27dd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
27de0 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
27df0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
27e00 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
27e10 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
27e20 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
27e30 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
27e40 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
27e50 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
27e60 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
27e70 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
27e80 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
27e90 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
27ea0 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
27eb0 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
27ec0 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
27ed0 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
27ee0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
27ef0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
27f00 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
27f10 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
27f20 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
27f30 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
27f40 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
27f50 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
27f60 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
27f70 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
27f80 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
27f90 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
27fa0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
27fb0 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
27fc0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
27fd0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
27fe0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
27ff0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
28000 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
28010 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
28020 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
28030 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
28040 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
28050 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
28060 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
28070 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
28080 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
28090 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
280a0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
280b0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
280c0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
280d0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
280e0 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
280f0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
28100 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
28110 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
28120 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
28130 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
28140 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
28150 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
28160 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
28170 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
28180 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
28190 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
281a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
281b0 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
281c0 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
281d0 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
281e0 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
281f0 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
28200 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
28210 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
28220 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
28230 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
28240 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
28250 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
28260 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
28270 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
28280 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
28290 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
282a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
282b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
282c0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
282d0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
282e0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
282f0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
28300 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
28310 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
28320 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
28330 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
28340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28350 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
28360 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
28370 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
28380 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
28390 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
283a0 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
283b0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
283c0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
283d0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
283e0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
283f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
28400 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
28410 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
28420 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
28430 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
28440 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
28450 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
28460 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
28470 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
28480 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
28490 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
284a0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
284b0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
284c0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
284d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
284e0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
284f0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
28500 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
28510 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
28520 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
28530 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
28540 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
28550 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
28560 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
28570 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
28580 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
28590 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
285a0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
285b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
285c0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
285d0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
285e0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
285f0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
28600 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
28610 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
28620 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
28630 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
28640 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  iners for all th
28650 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
28660 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
28670 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
28680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28690 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
286a0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
286b0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
286c0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
286d0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
286e0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
286f0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
28700 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
28710 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
28720 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
28730 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
28740 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
28750 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
28760 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
28770 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
28780 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
28790 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
287a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
287b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
287c0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
287d0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
287e0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
287f0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
28800 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
28810 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
28820 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
28830 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
28840 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
28850 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
28860 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
28870 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
28880 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28890 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
288a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
288b0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
288c0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
288d0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
288e0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
288f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
28900 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
28910 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
28920 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
28930 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
28940 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
28950 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
28960 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
28970 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
28980 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
28990 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
289a0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
289b0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
289c0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
289d0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
289e0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
289f0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
28a00 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
28a10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
28a20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
28a30 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
28a40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
28a50 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
28a60 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
28a70 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
28a80 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
28a90 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
28aa0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
28ab0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
28ac0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
28ad0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
28ae0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
28af0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
28b00 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
28b10 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
28b20 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
28b30 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
28b40 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
28b50 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
28b60 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
28b70 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
28b80 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
28b90 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
28ba0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
28bb0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
28bc0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
28bd0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
28be0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28bf0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
28c00 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
28c10 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28c20 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
28c30 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
28c40 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
28c50 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
28c60 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
28c70 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
28c80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28c90 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
28ca0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
28cb0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
28cc0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
28cd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
28ce0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
28cf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28d00 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
28d10 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
28d20 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
28d30 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
28d40 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
28d50 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
28d60 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
28d70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
28d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
28d90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
28da0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
28db0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
28dc0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
28dd0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
28de0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
28df0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
28e00 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
28e10 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
28e20 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
28e30 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
28e40 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
28e50 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
28e60 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
28e70 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
28e80 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
28e90 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
28ea0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
28eb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
28ec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
28ed0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
28ee0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
28ef0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
28f00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28f10 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
28f20 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
28f30 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
28f40 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
28f50 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
28f60 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
28f70 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
28f80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
28f90 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
28fa0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
28fb0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
28fc0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
28fd0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
28fe0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
28ff0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
29000 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
29010 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
29020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
29030 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
29040 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
29050 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
29060 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
29070 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
29080 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
29090 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
290a0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
290b0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
290c0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
290d0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
290e0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
290f0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
29100 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
29110 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
29120 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
29130 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
29140 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
29150 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
29160 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
29170 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29180 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
29190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
291a0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
291b0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
291c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
291d0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
291e0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
291f0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
29200 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
29210 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
29220 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
29230 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
29240 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
29250 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
29260 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
29270 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
29280 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
29290 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
292a0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
292b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
292c0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
292d0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
292e0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
292f0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
29300 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
29310 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
29320 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
29330 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
29340 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
29350 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
29360 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
29370 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
29380 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
29390 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
293a0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
293b0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
293c0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
293d0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
293e0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
293f0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
29400 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
29410 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
29420 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
29430 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
29440 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
29450 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
29460 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
29470 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29480 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
29490 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
294a0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
294b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
294c0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
294d0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
294e0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
294f0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
29500 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
29510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
29520 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
29530 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
29540 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
29550 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
29560 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
29570 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
29580 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
29590 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
295a0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
295b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
295c0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
295d0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
295e0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
295f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
29600 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
29610 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
29620 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
29630 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
29640 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
29650 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
29660 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
29670 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
29680 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
29690 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
296a0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
296b0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
296c0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
296d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
296e0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
296f0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
29700 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
29710 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29720 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
29730 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
29740 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
29750 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
29760 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
29770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
29780 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
29790 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
297a0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
297b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
297c0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
297d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
297e0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
297f0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
29800 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
29810 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
29820 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
29830 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
29840 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
29850 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
29860 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
29870 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
29880 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
29890 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
298a0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
298b0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
298c0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
298d0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
298e0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
298f0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
29900 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
29910 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29920 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
29930 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
29940 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
29950 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
29960 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
29970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29980 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29990 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
299a0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
299b0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
299c0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
299d0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
299e0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
299f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
29a00 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
29a10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
29a20 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
29a30 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
29a40 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
29a50 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
29a60 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
29a70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
29a80 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
29a90 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
29aa0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
29ab0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
29ac0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
29ad0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
29ae0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
29af0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
29b00 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
29b10 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
29b20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
29b30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
29b40 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
29b50 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
29b60 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
29b70 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
29b80 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
29b90 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
29ba0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
29bb0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
29bc0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
29bd0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
29be0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
29bf0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
29c00 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
29c10 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
29c20 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
29c30 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
29c40 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
29c50 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
29c60 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
29c70 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
29c80 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
29c90 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
29ca0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
29cb0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
29cc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
29cd0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
29ce0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
29cf0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
29d00 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
29d10 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
29d20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
29d30 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
29d40 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
29d50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
29d60 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
29d70 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
29d80 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
29d90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
29da0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
29db0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
29dc0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
29dd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
29de0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
29df0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
29e00 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
29e10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29e20 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
29e30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
29e40 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
29e50 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
29e60 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29e70 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
29e80 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29e90 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
29ea0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
29eb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
29ec0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
29ed0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
29ee0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
29ef0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
29f00 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
29f10 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
29f20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
29f30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
29f40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29f50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
29f60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
29f70 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
29f80 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
29f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
29fa0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
29fb0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
29fc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
29fd0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
29fe0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
29ff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2a000 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2a010 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2a020 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2a030 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2a040 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a050 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2a060 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2a070 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
2a080 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2a090 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2a0a0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2a0b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
2a0c0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
2a0d0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2a0e0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
2a0f0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2a100 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2a110 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2a120 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2a130 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
2a140 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2a150 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
2a160 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
2a170 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
2a180 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
2a190 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2a1a0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a1b0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
2a1c0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
2a1d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2a1e0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2a1f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2a200 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2a210 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2a220 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
2a230 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2a240 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
2a250 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2a260 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
2a270 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
2a280 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
2a290 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
2a2a0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
2a2b0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
2a2c0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
2a2d0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
2a2e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
2a2f0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
2a300 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
2a310 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
2a320 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
2a330 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2a340 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
2a350 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
2a360 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
2a370 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
2a380 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
2a390 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
2a3a0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
2a3b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2a3c0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
2a3d0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
2a3e0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
2a3f0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
2a400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a410 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2a420 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
2a430 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2a440 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
2a450 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
2a460 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
2a470 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2a480 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
2a490 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
2a4a0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
2a4b0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
2a4c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2a4d0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
2a4e0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2a4f0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
2a500 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
2a510 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
2a520 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
2a530 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
2a540 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2a550 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2a560 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
2a570 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2a580 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2a590 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
2a5a0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
2a5b0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
2a5c0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2a5d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2a5e0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
2a5f0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
2a600 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2a610 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
2a620 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
2a630 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2a640 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2a650 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2a660 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
2a670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2a680 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
2a690 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
2a6a0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
2a6b0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
2a6c0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
2a6d0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
2a6e0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
2a6f0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
2a700 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
2a710 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2a720 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2a730 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2a740 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2a750 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2a760 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2a770 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2a780 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2a790 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2a7a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2a7b0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2a7c0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2a7d0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2a7e0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2a7f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2a800 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2a810 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2a820 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2a830 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2a840 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2a850 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2a860 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2a870 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a880 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2a890 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a8a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2a8b0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2a8c0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2a8d0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2a8e0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2a8f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2a900 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2a910 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2a920 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2a930 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2a940 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2a960 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2a970 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2a980 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a990 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a9a0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2a9b0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
2a9c0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2a9d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2a9e0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2a9f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2aa00 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2aa10 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2aa20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2aa30 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2aa40 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2aa50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2aa60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2aa70 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2aa80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2aa90 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2aaa0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2aab0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2aac0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2aad0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
2aae0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2aaf0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2ab00 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2ab10 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2ab20 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2ab30 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
2ab40 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2ab50 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2ab60 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2ab70 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2ab80 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2ab90 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
2aba0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2abb0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2abc0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2abd0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2abe0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2abf0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2ac00 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2ac10 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2ac20 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2ac30 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2ac40 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
2ac50 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
2ac60 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
2ac70 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
2ac80 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
2ac90 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
2aca0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
2acb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
2acc0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
2acd0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
2ace0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
2acf0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
2ad00 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2ad10 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2ad20 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2ad30 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2ad40 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
2ad50 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
2ad60 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2ad70 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
2ad80 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
2ad90 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2ada0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2adb0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
2adc0 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
2add0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
2ade0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
2adf0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
2ae00 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2ae10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2ae20 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2ae30 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2ae40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
2ae50 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
2ae60 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
2ae70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2ae80 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
2ae90 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2aea0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
2aeb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2aec0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
2aed0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
2aee0 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
2aef0 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2af00 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
2af10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
2af20 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
2af30 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
2af40 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
2af50 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
2af60 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
2af70 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
2af80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2af90 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
2afa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2afb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2afc0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2afd0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2afe0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
2aff0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
2b000 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
2b010 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
2b020 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
2b030 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
2b040 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b050 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
2b060 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2b070 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
2b080 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
2b090 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
2b0a0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
2b0b0 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
2b0c0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
2b0d0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
2b0e0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2b0f0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
2b100 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2b110 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2b120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2b130 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2b140 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
2b150 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2b160 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2b170 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2b180 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2b190 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2b1a0 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2b1b0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2b1c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2b1d0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2b1e0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2b1f0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
2b200 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
2b210 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2b220 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
2b230 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2b240 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
2b250 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2b260 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2b270 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2b280 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
2b290 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
2b2a0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
2b2b0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2b2c0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2b2d0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2b2e0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2b2f0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2b300 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2b310 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2b320 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
2b330 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
2b340 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2b350 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2b360 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2b370 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2b380 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2b390 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2b3a0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
2b3b0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2b3c0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
2b3d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
2b3e0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2b3f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2b400 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
2b410 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
2b420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2b430 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
2b440 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
2b450 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
2b460 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2b470 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
2b480 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2b490 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2b4a0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2b4b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2b4c0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2b4d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2b4e0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
2b4f0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2b500 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2b510 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2b520 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2b530 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2b540 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2b550 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2b560 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2b570 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2b580 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
2b590 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2b5a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2b5b0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2b5c0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2b5d0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2b5e0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2b5f0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2b600 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2b610 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2b620 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2b630 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2b640 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2b650 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2b660 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2b670 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2b680 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2b690 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2b6a0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2b6b0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2b6c0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2b6d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2b6e0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2b6f0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2b700 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2b710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2b720 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2b730 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2b740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b750 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
2b760 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
2b770 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
2b780 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2b790 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
2b7a0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
2b7b0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
2b7c0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
2b7d0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2b7e0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
2b7f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b800 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2b810 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b820 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2b830 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2b840 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2b850 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2b860 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
2b870 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
2b880 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
2b890 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
2b8a0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
2b8b0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
2b8c0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
2b8d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b8e0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
2b8f0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
2b900 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
2b910 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
2b920 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2b930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b940 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
2b950 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2b960 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2b970 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
2b980 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b990 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
2b9a0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
2b9b0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
2b9c0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
2b9d0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
2b9e0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
2b9f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
2ba00 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
2ba10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2ba20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2ba30 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
2ba40 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
2ba50 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2ba60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ba70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2ba80 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
2ba90 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
2baa0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
2bab0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
2bac0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2bad0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2bae0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2baf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2bb00 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
2bb10 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2bb20 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2bb30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2bb40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2bb50 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2bb60 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
2bb70 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
2bb80 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2bb90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bba0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2bbb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2bbc0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
2bbd0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
2bbe0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
2bbf0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
2bc00 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
2bc10 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
2bc20 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2bc30 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2bc40 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2bc50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2bc60 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2bc70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2bc80 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2bc90 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2bca0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
2bcb0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
2bcc0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
2bcd0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2bce0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2bcf0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
2bd00 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
2bd10 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
2bd20 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2bd30 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
2bd40 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
2bd50 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
2bd60 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2bd70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2bd80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2bd90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2bda0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2bdb0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
2bdc0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
2bdd0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
2bde0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
2bdf0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
2be00 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2be10 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2be20 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2be30 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2be40 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
2be50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2be60 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
2be70 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2be80 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
2be90 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
2bea0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
2beb0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2bec0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
2bed0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
2bee0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bef0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2bf00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2bf10 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
2bf20 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
2bf30 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
2bf40 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2bf50 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
2bf60 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
2bf70 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
2bf80 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
2bf90 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
2bfa0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
2bfb0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
2bfc0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
2bfd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bfe0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
2bff0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
2c000 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
2c010 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
2c020 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
2c030 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
2c040 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
2c050 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
2c060 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
2c070 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
2c080 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2c090 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2c0a0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2c0b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c0c0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
2c0d0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
2c0e0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
2c0f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c100 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
2c110 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2c120 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
2c130 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
2c140 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2c150 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2c160 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
2c170 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
2c180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c190 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
2c1a0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2c1b0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2c1c0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2c1d0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
2c1e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
2c1f0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
2c200 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c210 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
2c220 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2c230 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2c240 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c250 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c260 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
2c270 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2c280 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2c290 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2c2a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c2b0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
2c2c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2c2d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2c2e0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2c2f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2c300 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2c310 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2c320 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2c330 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2c340 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2c350 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c360 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
2c370 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2c380 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2c390 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2c3a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2c3b0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
2c3c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c3d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
2c3e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c3f0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
2c400 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2c410 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
2c420 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2c430 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
2c440 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
2c450 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
2c460 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c470 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c480 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
2c490 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
2c4a0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
2c4b0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
2c4c0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
2c4d0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
2c4e0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
2c4f0 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
2c500 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
2c510 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2c520 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2c530 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2c540 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2c550 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2c560 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c570 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2c580 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2c590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2c5a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c5b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2c5c0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2c5d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2c5e0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2c5f0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2c600 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
2c610 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2c620 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
2c630 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2c640 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2c650 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2c660 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2c670 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2c680 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2c690 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2c6a0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2c6b0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2c6c0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2c6d0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
2c6e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c6f0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
2c700 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
2c710 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2c720 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2c730 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2c740 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
2c750 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2c760 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
2c770 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2c780 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
2c790 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
2c7a0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
2c7b0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
2c7c0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
2c7d0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2c7e0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2c7f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2c800 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2c810 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2c820 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2c830 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
2c840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c850 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2c860 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2c870 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
2c880 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
2c890 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
2c8a0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2c8b0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
2c8c0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2c8d0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
2c8e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
2c8f0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
2c900 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
2c910 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
2c920 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2c930 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2c940 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2c950 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2c960 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2c970 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2c980 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2c990 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2c9a0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2c9b0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2c9c0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
2c9d0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
2c9e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
2c9f0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
2ca00 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
2ca10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2ca20 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
2ca30 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
2ca40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2ca50 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
2ca60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2ca70 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2ca80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ca90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2caa0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
2cab0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2cac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cad0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
2cae0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2caf0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
2cb00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2cb10 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
2cb20 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2cb30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2cb40 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
2cb50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2cb60 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
2cb70 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
2cb80 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
2cb90 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
2cba0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
2cbb0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
2cbc0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
2cbd0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
2cbe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2cbf0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
2cc00 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
2cc10 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2cc20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cc30 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
2cc40 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
2cc50 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
2cc60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cc70 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
2cc80 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
2cc90 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
2cca0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2ccb0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
2ccc0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
2ccd0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
2cce0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
2ccf0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
2cd00 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2cd10 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
2cd20 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2cd30 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
2cd40 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
2cd50 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2cd60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2cd70 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
2cd80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2cd90 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2cda0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2cdb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2cdc0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
2cdd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
2cde0 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
2cdf0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
2ce00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2ce10 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2ce20 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2ce30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2ce40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ce50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2ce60 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2ce70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2ce80 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2ce90 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2cea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ceb0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
2cec0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2ced0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cee0 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2cef0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2cf00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2cf10 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
2cf20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2cf30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2cf40 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
2cf50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2cf60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
2cf70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2cf80 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
2cf90 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2cfa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cfb0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2cfc0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2cfd0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2cfe0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2cff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d000 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
2d010 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d020 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2d030 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2d040 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d050 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
2d060 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2d070 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2d080 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2d090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d0a0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
2d0b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2d0c0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2d0d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2d0e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d0f0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
2d100 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
2d110 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
2d120 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2d130 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2d140 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
2d150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d160 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
2d170 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
2d180 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2d190 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
2d1a0 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
2d1b0 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
2d1c0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2d1d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d1e0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2d1f0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
2d200 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2d210 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2d220 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
2d230 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
2d240 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2d250 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
2d260 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
2d270 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
2d280 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
2d290 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
2d2a0 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
2d2b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2d2c0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
2d2d0 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
2d2e0 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
2d2f0 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
2d300 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
2d310 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
2d320 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
2d330 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
2d340 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
2d350 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
2d360 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
2d370 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
2d380 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
2d390 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
2d3a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
2d3b0 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
2d3c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2d3d0 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
2d3e0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
2d3f0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
2d400 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
2d410 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
2d420 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
2d430 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
2d440 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2d450 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
2d460 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
2d470 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
2d480 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
2d490 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
2d4a0 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
2d4b0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2d4c0 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
2d4d0 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
2d4e0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
2d4f0 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
2d500 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
2d510 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
2d520 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
2d530 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
2d540 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
2d550 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
2d560 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
2d570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2d580 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
2d590 72 67 2c 20 69 73 20 61 20 61 70 70 6c 69 63 61  rg, is a applica
2d5a0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2d5b0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2d5c0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
2d5d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d5e0 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
2d5f0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
2d600 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
2d610 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
2d620 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
2d630 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d640 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d650 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
2d660 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2d670 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
2d680 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
2d690 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
2d6a0 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
2d6b0 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
2d6c0 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
2d6d0 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
2d6e0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
2d6f0 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
2d700 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2d710 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
2d720 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
2d730 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
2d740 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
2d750 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d760 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
2d770 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
2d780 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
2d790 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
2d7a0 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
2d7b0 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
2d7c0 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
2d7d0 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
2d7e0 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
2d7f0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2d800 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
2d810 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
2d820 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
2d830 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2d840 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
2d850 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
2d860 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
2d870 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
2d880 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
2d890 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2d8a0 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
2d8b0 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
2d8c0 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
2d8d0 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
2d8e0 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
2d8f0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
2d900 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
2d910 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
2d920 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
2d930 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2d940 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
2d950 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 20  tion must alway 
2d960 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
2d970 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
2d980 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
2d990 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
2d9a0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2d9b0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
2d9c0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
2d9d0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
2d9e0 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
2d9f0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
2da00 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
2da10 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
2da20 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
2da30 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
2da40 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
2da50 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
2da60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2da70 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
2da80 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
2da90 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
2daa0 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
2dab0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2dac0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
2dad0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
2dae0 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
2daf0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
2db00 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
2db10 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
2db20 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
2db30 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
2db40 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
2db50 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
2db60 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
2db70 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
2db80 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
2db90 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
2dba0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
2dbb0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
2dbc0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2dbd0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
2dbe0 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
2dbf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2dc00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2dc10 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
2dc20 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
2dc30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2dc40 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
2dc50 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
2dc60 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
2dc70 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
2dc80 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
2dc90 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2dca0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
2dcb0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
2dcc0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
2dcd0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
2dce0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
2dcf0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
2dd00 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
2dd10 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
2dd20 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
2dd30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2dd40 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
2dd50 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2dd60 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2dd70 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
2dd80 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
2dd90 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
2dda0 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
2ddb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ddc0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
2ddd0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
2dde0 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
2ddf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2de00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2de10 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
2de20 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
2de30 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
2de40 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
2de50 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
2de60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2de70 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2de80 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
2de90 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
2dea0 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
2deb0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
2dec0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
2ded0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
2dee0 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
2def0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
2df00 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
2df10 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
2df20 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
2df30 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
2df40 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
2df50 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
2df60 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
2df70 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
2df80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2df90 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
2dfa0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2dfb0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
2dfc0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2dfd0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
2dfe0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2dff0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
2e000 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2e010 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
2e020 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2e030 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2e040 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2e050 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
2e060 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e070 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2e080 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2e090 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2e0a0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2e0b0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
2e0c0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2e0d0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2e0e0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2e0f0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2e100 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2e110 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2e120 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
2e130 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2e140 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
2e150 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2e160 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
2e170 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2e180 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2e190 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2e1a0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
2e1b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2e1c0 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
2e1d0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2e1e0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
2e1f0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
2e200 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2e210 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
2e220 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
2e230 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
2e240 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2e250 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
2e260 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
2e270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e280 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
2e290 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
2e2a0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2e2b0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
2e2c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2e2d0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
2e2e0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
2e2f0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2e300 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2e310 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
2e320 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
2e330 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
2e340 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
2e350 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
2e360 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
2e370 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
2e380 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e390 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
2e3a0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
2e3b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
2e3c0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
2e3d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2e3e0 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
2e3f0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
2e400 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
2e410 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
2e420 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
2e430 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
2e440 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2e450 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
2e460 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
2e470 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
2e480 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
2e490 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2e4a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2e4b0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
2e4c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2e4d0 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
2e4e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2e4f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2e500 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
2e510 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2e520 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2e530 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2e540 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
2e550 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2e560 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
2e570 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
2e580 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
2e590 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2e5a0 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
2e5b0 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
2e5c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2e5d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
2e5e0 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
2e5f0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
2e600 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
2e610 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
2e620 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
2e630 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
2e640 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
2e650 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e660 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
2e670 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e680 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
2e690 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e6a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
2e6b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e6c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2e6d0 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
2e6e0 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
2e6f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2e700 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
2e710 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
2e720 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2e730 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
2e740 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2e750 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
2e760 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
2e770 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
2e780 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
2e790 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
2e7a0 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
2e7b0 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
2e7c0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
2e7d0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
2e7e0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
2e7f0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
2e800 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
2e810 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
2e820 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2e830 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2e840 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2e850 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2e860 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2e870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
2e880 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e8a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2e8b0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2e8c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2e8d0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2e8e0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
2e8f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
2e900 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
2e910 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
2e920 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
2e930 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
2e940 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
2e950 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
2e960 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
2e970 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
2e980 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2e990 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
2e9a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2e9b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2e9c0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2e9d0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2e9e0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2e9f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2ea00 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
2ea10 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2ea20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ea30 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2ea40 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2ea50 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2ea60 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2ea70 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
2ea80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2ea90 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2eaa0 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
2eab0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
2eac0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
2ead0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
2eae0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2eaf0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2eb00 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
2eb10 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2eb20 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2eb30 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2eb40 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2eb50 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
2eb60 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
2eb70 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2eb80 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2eb90 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
2eba0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2ebb0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2ebc0 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
2ebd0 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
2ebe0 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
2ebf0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
2ec00 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
2ec10 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2ec20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2ec30 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2ec40 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2ec50 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
2ec60 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
2ec70 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
2ec80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
2ec90 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
2eca0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
2ecb0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
2ecc0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
2ecd0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
2ece0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2ecf0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
2ed00 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
2ed10 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
2ed20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
2ed30 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
2ed40 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
2ed50 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
2ed60 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
2ed70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
2ed80 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
2ed90 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
2eda0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
2edb0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
2edc0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2edd0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2ede0 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2edf0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2ee00 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2ee10 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
2ee20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2ee30 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2ee40 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2ee50 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2ee60 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2ee70 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2ee80 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
2ee90 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
2eea0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
2eeb0 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
2eec0 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
2eed0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
2eee0 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
2eef0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ef00 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
2ef10 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
2ef20 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
2ef30 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
2ef40 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
2ef50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2ef60 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
2ef70 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2ef80 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
2ef90 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
2efa0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
2efb0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
2efc0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
2efd0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
2efe0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
2eff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
2f000 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
2f010 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
2f020 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
2f030 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2f040 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
2f050 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
2f060 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
2f070 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
2f080 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
2f090 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
2f0a0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
2f0b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
2f0c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
2f0d0 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
2f0e0 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
2f0f0 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
2f100 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
2f110 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
2f120 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2f130 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2f140 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
2f150 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
2f160 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
2f170 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2f180 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2f190 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
2f1a0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2f1b0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
2f1c0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
2f1d0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
2f1e0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
2f1f0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
2f200 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2f210 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
2f220 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
2f230 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
2f240 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
2f250 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
2f260 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
2f270 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
2f280 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
2f290 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
2f2a0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
2f2b0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
2f2c0 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
2f2d0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2f2e0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
2f2f0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
2f300 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
2f310 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2f320 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2f330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
2f340 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
2f350 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2f360 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2f370 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
2f380 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
2f390 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
2f3a0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
2f3b0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
2f3c0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2f3d0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
2f3e0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
2f3f0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
2f400 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
2f410 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
2f420 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
2f430 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
2f440 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
2f450 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
2f460 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
2f470 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
2f480 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
2f490 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
2f4a0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2f4b0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
2f4c0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
2f4d0 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2f4e0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2f4f0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
2f500 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
2f510 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
2f520 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
2f530 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
2f540 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
2f550 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
2f560 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
2f570 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
2f580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f590 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
2f5a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2f5b0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2f5c0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
2f5d0 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
2f5e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
2f5f0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2f600 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
2f610 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
2f620 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2f630 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
2f640 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
2f650 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
2f660 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
2f670 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
2f680 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
2f690 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
2f6a0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
2f6b0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
2f6c0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
2f6d0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
2f6e0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
2f6f0 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
2f700 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
2f710 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
2f720 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
2f730 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
2f740 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
2f750 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
2f760 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
2f770 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
2f780 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
2f790 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
2f7a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
2f7b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
2f7c0 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
2f7d0 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
2f7e0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2f7f0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2f800 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2f810 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
2f820 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
2f830 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
2f840 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
2f850 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
2f860 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
2f870 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
2f880 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2f890 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
2f8a0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
2f8b0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
2f8c0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
2f8d0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
2f8e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
2f8f0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
2f900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f910 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
2f920 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
2f930 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2f940 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2f950 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
2f960 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f970 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f980 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2f990 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
2f9a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f9b0 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
2f9c0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
2f9d0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
2f9e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f9f0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
2fa00 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2fa10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2fa20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
2fa30 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
2fa40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
2fa50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
2fa60 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
2fa70 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
2fa80 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
2fa90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
2faa0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2fab0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2fac0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
2fad0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2fae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2faf0 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
2fb00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fb10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2fb20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2fb30 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2fb40 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
2fb50 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
2fb60 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
2fb70 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2fb80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fb90 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74  n] pDb.  ^If pSt
2fba0 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
2fbb0 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
2fbc0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2fbd0 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
2fbe0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2fbf0 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
2fc00 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
2fc10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
2fc20 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70  Db.  ^If no prep
2fc30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2fc40 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
2fc50 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
2fc60 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72  is routine, it r
2fc70 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  eturns NULL..**.
2fc80 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  ** The [database
2fc90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
2fca0 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
2fcb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2fcc0 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20  next_stmt(D,S)] 
2fcd0 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e  must refer to an
2fce0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a   open database.*
2fcf0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  * connection and
2fd00 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
2fd10 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
2fd20 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
2fd30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
2fd40 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
2fd50 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
2fd60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2fd70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fd80 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
2fd90 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
2fda0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
2fdb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fdc0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
2fdd0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2fde0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2fdf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fe00 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2fe10 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2fe20 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
2fe30 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
2fe40 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2fe50 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2fe60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
2fe70 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
2fe80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2fe90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2fea0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
2feb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
2fec0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
2fed0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2fee0 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
2fef0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
2ff00 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2ff10 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
2ff20 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
2ff30 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
2ff40 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2ff50 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2ff60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
2ff70 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
2ff80 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2ff90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ffa0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2ffb0 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
2ffc0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
2ffd0 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
2ffe0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
2fff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
30000 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
30010 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
30020 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
30030 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
30040 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
30050 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
30060 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
30070 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
30080 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
30090 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
300a0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
300b0 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
300c0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
300d0 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
300e0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
300f0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
30100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30110 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
30120 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
30130 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
30140 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
30150 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
30160 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
30170 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
30180 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
30190 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
301a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
301b0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
301c0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20   callback.  Any 
301d0 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
301e0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
301f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
30200 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
30210 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
30220 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
30230 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
30240 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
30250 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d  iggered the comm
30260 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63  it.** or rollbac
30270 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69  k hook in the fi
30280 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f  rst place..** No
30290 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
302a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
302b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
302c0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
302d0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
302e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
302f0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
30300 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
30310 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
30320 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
30330 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
30340 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
30350 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
30360 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
30370 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
30380 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
30390 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
303a0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
303b0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
303c0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
303d0 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
303e0 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
303f0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
30400 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
30410 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
30420 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
30430 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
30440 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
30450 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
30460 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
30470 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
30480 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
30490 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
304a0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
304b0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
304c0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
304d0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
304e0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
304f0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
30500 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
30510 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
30520 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
30530 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
30540 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
30550 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
30560 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
30570 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
30580 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
30590 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
305a0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
305b0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
305c0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
305d0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
305e0 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
305f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30600 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
30610 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
30620 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
30630 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
30640 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
30650 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
30660 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
30670 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
30680 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
30690 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
306a0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
306b0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
306c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
306d0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
306e0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
306f0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
30700 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
30710 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
30720 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
30730 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
30740 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
30750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
30760 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
30770 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
30780 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
30790 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
307a0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
307b0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
307c0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
307d0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
307e0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
307f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
30800 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
30820 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
30830 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
30840 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
30850 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
30860 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
30870 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
30880 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
30890 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
308a0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
308b0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
308c0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
308d0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
308e0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
308f0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
30900 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
30910 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
30920 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
30930 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
30940 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
30950 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
30960 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
30970 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
30980 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
30990 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
309a0 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
309b0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
309c0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
309d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
309e0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
309f0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
30a00 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
30a10 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
30a20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
30a30 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
30a40 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
30a50 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
30a60 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
30a70 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
30a80 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
30a90 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
30aa0 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
30ab0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
30ac0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
30ad0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
30ae0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
30af0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
30b00 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
30b10 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
30b20 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
30b30 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
30b40 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
30b50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
30b60 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
30b70 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
30b80 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
30b90 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
30ba0 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
30bb0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
30bc0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
30bd0 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
30be0 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
30bf0 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
30c00 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
30c10 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
30c20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
30c30 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
30c40 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
30c50 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
30c60 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
30c70 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
30c80 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
30c90 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
30ca0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
30cb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
30cc0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
30cd0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
30ce0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
30cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
30d00 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
30d10 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
30d20 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
30d30 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
30d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
30d50 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
30d60 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
30d70 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
30d80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
30d90 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
30da0 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
30db0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
30dc0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
30dd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
30de0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
30df0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
30e00 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
30e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
30e20 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
30e30 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
30e40 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
30e50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
30e60 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
30e70 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
30e80 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
30e90 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
30ea0 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
30eb0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
30ec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30ed0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
30ee0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
30ef0 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
30f00 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
30f10 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
30f20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30f30 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
30f40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  .** interfaces..
30f50 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
30f60 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
30f70 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
30f80 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
30f90 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
30fa0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
30fb0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
30fc0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
30fd0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
30fe0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
30ff0 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
31000 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
31010 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
31020 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
31030 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
31040 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
31050 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
31060 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
31070 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
31080 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
31090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
310a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
310b0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
310c0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
310d0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
310e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
310f0 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
31100 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
31110 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
31120 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
31130 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
31140 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
31150 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
31160 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
31170 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
31180 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
31190 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
311a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
311b0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
311c0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
311d0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
311e0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
311f0 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
31200 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
31210 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
31220 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
31230 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
31240 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
31250 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
31260 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
31270 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
31280 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
31290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
312a0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
312b0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
312c0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
312d0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
312e0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
312f0 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
31300 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
31310 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
31320 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
31330 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
31340 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
31350 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
31360 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
31370 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
31380 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
31390 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
313a0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
313b0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
313c0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
313d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
313e0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
313f0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
31400 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
31410 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
31420 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
31430 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
31440 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
31450 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
31460 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
31470 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
31480 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
31490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
314a0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
314b0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
314c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
314d0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
314e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
314f0 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
31500 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
31510 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
31520 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
31530 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
31540 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
31550 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
31560 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
31570 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
31580 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
31590 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
315a0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
315b0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
315c0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
315d0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
315e0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
315f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31600 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
31610 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
31620 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
31630 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
31640 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
31650 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31660 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
31670 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d  routine is a no-
31680 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72  op returning zer
31690 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  o.** if SQLite i
316a0 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77  s not compiled w
316b0 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
316c0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
316d0 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  MENT]..*/.int sq
316e0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
316f0 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
31700 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f  * CAPI3REF: Impo
31710 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
31720 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54  ap Size.**.** ^T
31730 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
31740 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69  heap_limit64() i
31750 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e  nterface sets an
31760 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65  d/or queries the
31770 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f  .** soft limit o
31780 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
31790 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
317a0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
317b0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
317c0 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20  ^SQLite strives 
317d0 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d  to keep heap mem
317e0 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20  ory utilization 
317f0 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68  below the soft h
31800 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20  eap.** limit by 
31810 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d  reducing the num
31820 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c  ber of pages hel
31830 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61  d in the page ca
31840 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d  che.** as heap m
31850 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70  emory usages app
31860 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69  roaches the limi
31870 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20  t..** ^The soft 
31880 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73  heap limit is "s
31890 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65  oft" because eve
318a0 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20  n though SQLite 
318b0 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a  strives to stay.
318c0 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d  ** below the lim
318d0 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65  it, it will exce
318e0 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74  ed the limit rat
318f0 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74  her than generat
31900 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f  e.** an [SQLITE_
31910 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49  NOMEM] error.  I
31920 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
31930 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31940 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f  it .** is adviso
31950 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ry only..**.** ^
31960 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
31970 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f   from sqlite3_so
31980 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
31990 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  ) is the size of
319a0 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61  .** the soft hea
319b0 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f  p limit prior to
319c0 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20   the call.  ^If 
319d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
319e0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68  s negative.** th
319f0 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20  en no change is 
31a00 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74  made to the soft
31a10 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65   heap limit.  He
31a20 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74  nce, the current
31a30 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20  .** size of the 
31a40 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
31a50 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
31a60 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  d by invoking.**
31a70 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
31a80 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74  ap_limit64() wit
31a90 68 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67  h a negative arg
31aa0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ument..**.** ^If
31ab0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20   the argument N 
31ac0 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65  is zero then the
31ad0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
31ae0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
31af0 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68  .** ^(The soft h
31b00 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  eap limit is not
31b10 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65   enforced in the
31b20 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
31b30 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e  ntation.** if on
31b40 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c  e or more of fol
31b50 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e  lowing condition
31b60 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a  s are true:.**.*
31b70 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
31b80 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31b90 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72  it is set to zer
31ba0 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72  o..** <li> Memor
31bb0 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20  y accounting is 
31bc0 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
31bd0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
31be0 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  the.**      [sql
31bf0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
31c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
31c10 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72  TATUS],...) star
31c20 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e  t-time option an
31c30 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53  d.**      the [S
31c40 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
31c50 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65  MSTATUS] compile
31c60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
31c70 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61   <li> An alterna
31c80 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20  tive page cache 
31c90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
31ca0 73 20 73 70 65 63 69 66 65 64 20 75 73 69 6e 67  s specifed using
31cb0 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
31cc0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
31cd0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
31ce0 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ,...)..** <li> T
31cf0 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c  he page cache al
31d00 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73  locates from its
31d10 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c   own memory pool
31d20 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20   supplied.**    
31d30 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f    by [sqlite3_co
31d40 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
31d50 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c  NFIG_PAGECACHE],
31d60 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e  ...) rather than
31d70 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68  .**      from th
31d80 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e  e heap..** </ul>
31d90 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69  )^.**.** Beginni
31da0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
31db0 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68  ersion 3.7.3, th
31dc0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31dd0 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  t is enforced.**
31de0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
31df0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
31e00 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
31e10 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
31e20 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  NT].** compile-t
31e30 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ime option is in
31e40 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51  voked.  With [SQ
31e50 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
31e60 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a  RY_MANAGEMENT],.
31e70 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
31e80 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
31e90 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f  ed on every memo
31ea0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  ry allocation.  
31eb0 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49  Without.** [SQLI
31ec0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
31ed0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68  _MANAGEMENT], th
31ee0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31ef0 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63  t is only enforc
31f00 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72  ed.** when memor
31f10 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
31f20 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  y the page cache
31f30 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65  .  Testing sugge
31f40 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65  sts that because
31f50 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63  .** the page cac
31f60 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d  he is the predom
31f70 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65  inate memory use
31f80 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73  r in SQLite, mos
31f90 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
31fa0 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61  s will achieve a
31fb0 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61  dequate soft hea
31fc0 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d  p limit enforcem
31fd0 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74  ent without.** t
31fe0 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54  he use of [SQLIT
31ff0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
32000 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a  MANAGEMENT]..**.
32010 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61  ** The circumsta
32020 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68  nces under which
32030 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66   SQLite will enf
32040 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65  orce the soft he
32050 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20  ap limit may.** 
32060 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72  changes in futur
32070 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
32080 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  Lite..*/.sqlite3
32090 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73  _int64 sqlite3_s
320a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
320b0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e  (sqlite3_int64 N
320c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
320d0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53  EF: Deprecated S
320e0 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49  oft Heap Limit I
320f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52  nterface.** DEPR
32100 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69  ECATED.**.** Thi
32110 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65  s is a deprecate
32120 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
32130 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
32140 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
32150 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  * interface.  Th
32160 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72  is routine is pr
32170 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f  ovided for histo
32180 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
32190 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c  ity.** only.  Al
321a0 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  l new applicatio
321b0 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  ns should use th
321c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
321d0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
321e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74  )] interface rat
321f0 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e  her than this on
32200 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
32210 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
32220 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
32230 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f  imit(int N);.../
32240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
32250 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
32260 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
32270 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
32280 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
32290 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61  turns metadata a
322a0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
322b0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
322c0 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65  ific.** database
322d0 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
322e0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74  e using the [dat
322f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32300 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73  ] handle.** pass
32310 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
32320 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
32330 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  t..**.** ^The co
32340 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
32350 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
32360 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
32370 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
32380 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
32390 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  n. ^The second p
323a0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
323b0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
323c0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
323d0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
323e0 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63  mp", or an attac
323f0 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
32400 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
32410 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
32420 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20  or NULL. ^If it 
32430 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
32440 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
32450 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
32460 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
32470 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
32480 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
32490 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
324a0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
324b0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
324c0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
324d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  es..**.** ^The t
324e0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
324f0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
32500 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
32510 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
32520 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
32530 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
32540 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
32550 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
32560 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
32570 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
32580 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73  .** ^Metadata is
32590 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
325a0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
325b0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
325c0 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
325d0 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
325e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
325f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41  his function. ^A
32600 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75  ny of these argu
32610 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20  ments may be.** 
32620 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
32630 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
32640 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
32650 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69   metadata is omi
32660 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62  tted..**.** ^(<b
32670 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
32680 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
32690 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
326a0 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
326b0 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
326c0 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
326d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
326e0 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
326f0 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
32700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
32710 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
32720 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
32730 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
32740 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
32750 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
32760 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
32770 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
32780 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
32790 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
327a0 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
327b0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
327c0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
327d0 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
327e0 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
327f0 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
32800 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
32810 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
32820 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
32830 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
32840 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
32850 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
32860 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
32870 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
32880 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
32890 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72  or the.** declar
328a0 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
328b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
328c0 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
328d0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
328e0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51  * call to any SQ
328f0 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  Lite API functio
32900 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
32910 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
32920 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
32930 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
32940 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
32950 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32960 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
32970 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
32980 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
32990 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47  and an.** [INTEG
329a0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
329b0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
329c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
329d0 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
329e0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
329f0 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
32a00 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
32a10 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e  clared column. ^
32a20 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a  (If there is no.
32a30 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
32a40 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20  clared [INTEGER 
32a50 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
32a60 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
32a70 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
32a80 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f  rs are set as fo
32a90 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
32aa0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
32ab0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
32ac0 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
32ad0 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
32ae0 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
32af0 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
32b00 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
32b10 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
32b20 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  t: 0.** </pre>)^
32b30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
32b40 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
32b50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
32b60 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
32b70 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
32b80 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
32b90 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
32ba0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
32bb0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
32bc0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
32bd0 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
32be0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
32bf0 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
32c00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
32c10 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
32c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32c30 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
32c40 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
32c50 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a  _errmsg()).)^.**
32c60 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73  .** ^This API is
32c70 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
32c80 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
32c90 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
32ca0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
32cb0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
32cc0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
32cd0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
32ce0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
32cf0 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
32d00 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
32d10 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32d20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
32d30 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
32d40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
32d50 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
32d60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
32d70 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
32d80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
32d90 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
32da0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
32db0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
32dc0 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
32dd0 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
32de0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
32df0 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
32e00 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
32e10 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
32e20 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
32e30 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
32e40 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
32e50 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
32e60 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
32e70 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32e80 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
32e90 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
32ea0 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
32eb0 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
32ec0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
32ed0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
32ee0 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
32ef0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
32f00 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
32f10 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
32f20 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61  e if column is a
32f30 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
32f40 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32f50 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
32f60 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ension.**.** ^Th
32f70 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61  is interface loa
32f80 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74  ds an SQLite ext
32f90 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66  ension library f
32fa0 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69  rom the named fi
32fb0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  le..**.** ^The s
32fc0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
32fd0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
32fe0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f  e attempts to lo
32ff0 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  ad an.** SQLite 
33000 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
33010 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
33020 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a  he file zFile..*
33030 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20  *.** ^The entry 
33040 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a  point is zProc..
33050 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65  ** ^zProc may be
33060 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73   0, in which cas
33070 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
33080 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a  e entry point.**
33090 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
330a0 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
330b0 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73  init"..** ^The s
330c0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
330d0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
330e0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  e returns.** [SQ
330f0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
33100 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
33110 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
33120 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
33130 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
33140 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
33150 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
33160 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  en the.** [sqlit
33170 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
33180 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  n()] interface s
33190 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a  hall attempt to.
331a0 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  ** fill *pzErrMs
331b0 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  g with error mes
331c0 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
331d0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62   in memory.** ob
331e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
331f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
33200 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
33210 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66  tion.** should f
33220 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20  ree this memory 
33230 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
33240 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
33250 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
33260 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e  ading must be en
33270 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  abled using.** [
33280 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
33290 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
332a0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
332b0 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f  g this API,.** o
332c0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
332d0 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
332e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
332f0 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  so the [load_ext
33300 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e  ension() SQL fun
33310 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ction]..*/.int s
33320 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
33330 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
33340 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
33350 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
33360 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
33370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33380 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
33390 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
333a0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
333b0 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
333c0 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
333d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
333e0 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
333f0 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
33400 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
33410 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
33420 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
33430 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
33440 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
33450 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
33460 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
33470 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
33480 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
33490 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74  .** ^So as not t
334a0 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
334b0 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
334c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
334d0 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
334e0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
334f0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
33500 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
33510 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
33520 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
33530 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
33540 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
33550 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
33560 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
33570 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
33580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
33590 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
335a0 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
335b0 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  off..**.** ^Exte
335c0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
335d0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
335e0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
335f0 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20  3..** ^Call the 
33600 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
33610 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
33620 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
33630 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e  ff==1.** to turn
33640 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
33650 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69  ng on and call i
33660 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
33670 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61  to turn.** it ba
33680 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f  ck off again..*/
33690 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
336a0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
336b0 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  on(sqlite3 *db, 
336c0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
336d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
336e0 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
336f0 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65  Statically Linke
33700 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a  d Extensions.**.
33710 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
33720 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45  ce causes the xE
33730 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63  ntryPoint() func
33740 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
33750 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e  ed for.** each n
33760 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
33770 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73  nection] that is
33780 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69   created.  The i
33790 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74  dea here is that
337a0 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
337b0 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70  ) is the entry p
337c0 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69  oint for a stati
337d0 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c  cally linked SQL
337e0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a  ite extension.**
337f0 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61   that is to be a
33800 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61  utomatically loa
33810 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77  ded into all new
33820 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33830 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45  tions..**.** ^(E
33840 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66  ven though the f
33850 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70  unction prototyp
33860 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e  e shows that xEn
33870 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73  tryPoint() takes
33880 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  .** no arguments
33890 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69   and returns voi
338a0 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  d, SQLite invoke
338b0 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  s xEntryPoint() 
338c0 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72  with three.** ar
338d0 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65  guments and expe
338e0 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20  cts and integer 
338f0 72 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65  result as if the
33900 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68   signature of th
33910 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74  e.** entry point
33920 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77   where as follow
33930 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
33940 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e  uote><pre>.** &n
33950 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79  bsp;  int xEntry
33960 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b  Point(.** &nbsp;
33970 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c      sqlite3 *db,
33980 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f  .** &nbsp;    co
33990 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  nst char **pzErr
339a0 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  Msg,.** &nbsp;  
339b0 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
339c0 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
339d0 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26  nes *pThunk.** &
339e0 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70  nbsp;  );.** </p
339f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
33a00 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  )^.**.** If the 
33a10 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74  xEntryPoint rout
33a20 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  ine encounters a
33a30 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75  n error, it shou
33a40 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73  ld make *pzErrMs
33a50 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e  g.** point to an
33a60 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
33a70 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61  or message (obta
33a80 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
33a90 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a  e3_mprintf()]).*
33aa0 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  * and return an 
33ab0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
33ac0 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69  or code].  ^SQLi
33ad0 74 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20  te ensures that 
33ae0 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20  *pzErrMsg.** is 
33af0 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c  NULL before call
33b00 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f  ing the xEntryPo
33b10 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20  int().  ^SQLite 
33b20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b  will invoke.** [
33b30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
33b40 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74  on *pzErrMsg aft
33b50 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  er xEntryPoint()
33b60 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61   returns.  ^If a
33b70 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e  ny.** xEntryPoin
33b80 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65  t() returns an e
33b90 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74  rror, the [sqlit
33ba0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
33bb0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
33bc0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
33bd0 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74  pen_v2()] call t
33be0 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
33bf0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77   xEntryPoint() w
33c00 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  ill fail..**.** 
33c10 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
33c20 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
33c30 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79  X) with an entry
33c40 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73   point X that is
33c50 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74   already.** on t
33c60 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d  he list of autom
33c70 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
33c80 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33c90 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70  -op. ^No entry p
33ca0 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  oint.** will be 
33cb0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e  called more than
33cc0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64   once for each d
33cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33ce0 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65  on that is opene
33cf0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
33d00 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  o: [sqlite3_rese
33d10 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
33d20 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
33d30 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
33d40 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79  on(void (*xEntry
33d50 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a  Point)(void));..
33d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33d70 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
33d80 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
33d90 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  g.**.** ^This in
33da0 74 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73  terface disables
33db0 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65   all automatic e
33dc0 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f  xtensions previo
33dd0 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  usly.** register
33de0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
33df0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
33e00 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ()]..*/.void sql
33e10 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
33e20 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
33e30 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
33e40 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
33e50 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
33e60 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
33e70 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
33e80 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
33e90 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
33ea0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
33eb0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
33ec0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
33ed0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
33ee0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
33ef0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
33f00 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
33f10 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
33f20 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
33f30 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
33f40 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
33f50 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
33f60 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
33f70 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
33f80 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
33f90 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
33fa0 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
33fb0 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
33fc0 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
33fd0 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
33fe0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
33ff0 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
34000 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
34010 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
34020 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
34030 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
34040 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
34050 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
34060 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
34070 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
34080 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
34090 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
340a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
340b0 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65  rtual Table Obje
340c0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
340d0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
340e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
340f0 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  dule}.**.** This
34100 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65   structure, some
34110 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61  times called a a
34120 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   "virtual table 
34130 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66  module", .** def
34140 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65  ines the impleme
34150 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69  ntation of a [vi
34160 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20  rtual tables].  
34170 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
34180 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74  re consists most
34190 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
341a0 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
341b0 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74  .** ^A virtual t
341c0 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63  able module is c
341d0 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e  reated by fillin
341e0 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e  g in a persisten
341f0 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  t.** instance of
34200 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
34210 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f  and passing a po
34220 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  inter to that in
34230 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71  stance.** to [sq
34240 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
34250 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ule()] or [sqlit
34260 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
34270 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
34280 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
34290 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
342a0 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
342b0 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
342c0 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
342d0 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
342e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
342f0 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
34300 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
34310 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
34320 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
34330 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
34340 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
34350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
34360 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
34370 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
34380 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
34390 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
343a0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
343b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
343c0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
343d0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
343e0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
343f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
34400 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
34410 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
34420 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
34430 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
34440 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
34450 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
34460 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
34470 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
34480 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
34490 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
344a0 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
344b0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
344c0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
344d0 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
344e0 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
344f0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
34500 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
34510 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
34520 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
34530 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
34540 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
34550 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
34560 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
34570 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
34580 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34590 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
345a0 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
345b0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
345c0 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
345d0 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
345e0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
345f0 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
34600 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
34610 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
34620 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
34630 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
34640 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
34650 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
34660 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
34670 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
34680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34690 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
346a0 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
346b0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
346c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
346d0 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
346e0 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
346f0 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
34700 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
34710 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
34720 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
34730 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
34740 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
34750 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
34760 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
34770 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
34780 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
34790 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
347a0 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
347b0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
347c0 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
347d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
347e0 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
347f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
34800 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
34810 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
34820 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
34830 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
34840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
34850 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34860 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
34870 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
34880 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
34890 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
348a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
348b0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
348c0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
348d0 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
348e0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f  rmation.** KEYWO
348f0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64  RDS: sqlite3_ind
34900 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68  ex_info.**.** Th
34910 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
34920 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
34930 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
34940 75 72 65 73 20 69 73 20 75 73 65 64 20 61 73 20  ures is used as 
34950 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  part.** of the [
34960 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69  virtual table] i
34970 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70  nterface to.** p
34980 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
34990 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
349a0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
349b0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
349c0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
349d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
349e0 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
349f0 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
34a00 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
34a10 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
34a20 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
34a30 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
34a40 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
34a50 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
34a60 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
34a70 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  fields..**.** ^(
34a80 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
34a90 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
34aa0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
34ab0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20  straints of the 
34ac0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  form:.**.** <blo
34ad0 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f  ckquote>column O
34ae0 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f  P expr</blockquo
34af0 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  te>.**.** where 
34b00 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
34b10 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
34b20 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70  gt;=.)^  ^(The p
34b30 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74  articular operat
34b40 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20  or is.** stored 
34b50 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  in aConstraint[]
34b60 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  .op using one of
34b70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
34b80 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
34b90 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44  _EQ | SQLITE_IND
34ba0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76  EX_CONSTRAINT_ v
34bb0 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54  alues].)^.** ^(T
34bc0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
34bd0 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
34be0 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
34bf0 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20  nt[].iColumn.)^ 
34c00 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d   ^(aConstraint[]
34c10 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
34c20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
34c30 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
34c40 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
34c50 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
34c60 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
34c70 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
34c80 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
34c90 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  nnot.)^.**.** ^T
34ca0 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
34cb0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
34cc0 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
34cd0 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
34ce0 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
34cf0 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
34d00 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
34d10 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
34d20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
34d30 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
34d40 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
34d50 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
34d60 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
34d70 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61  sible..** ^The a
34d80 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
34d90 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ay only reports 
34da0 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
34db0 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72  ms that are.** r
34dc0 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70  elevant to the p
34dd0 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
34de0 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
34df0 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  eried..**.** ^In
34e00 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
34e10 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
34e20 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
34e30 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
34e40 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f  ^Each term of aO
34e50 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61  rderBy records a
34e60 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f   column of the O
34e70 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a  RDER BY clause..
34e80 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74  **.** The [xBest
34e90 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75  Index] method mu
34ea0 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
34eb0 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
34ec0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
34ed0 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
34ee0 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
34ef0 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72  xFilter.  ^If ar
34f00 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
34f10 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
34f20 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
34f30 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
34f40 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
34f50 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
34f60 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
34f70 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
34f80 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73  rgv.  ^(If aCons
34f90 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
34fa0 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
34fb0 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
34fc0 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
34fd0 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
34fe0 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
34ff0 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
35000 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
35010 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a  in by SQLite.)^.
35020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75  **.** ^The idxNu
35030 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c  m and idxPtr val
35040 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64  ues are recorded
35050 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f   and passed into
35060 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72   the.** [xFilter
35070 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73  ] method..** ^[s
35080 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
35090 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69  s used to free i
350a0 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c  dxPtr if and onl
350b0 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72  y if.** needToFr
350c0 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
350d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64  ..**.** ^The ord
350e0 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61  erByConsumed mea
350f0 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66  ns that output f
35100 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78  rom [xFilter]/[x
35110 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72  Next] will occur
35120 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
35130 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
35140 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
35150 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
35160 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
35170 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
35180 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
35190 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
351a0 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73  t value is an es
351b0 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f  timate of the co
351c0 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a  st of doing the.
351d0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f  ** particular lo
351e0 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63  okup.  A full sc
351f0 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69  an of a table wi
35200 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  th N entries sho
35210 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f  uld have.** a co
35220 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61  st of N.  A bina
35230 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74  ry search of a t
35240 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65  able of N entrie
35250 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a  s should have a.
35260 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f  ** cost of appro
35270 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e  ximately log(N).
35280 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
35290 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
352a0 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
352b0 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74   int nConstraint
352c0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ;           /* N
352d0 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
352e0 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
352f0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
35300 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
35310 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20  aint {.     int 
35320 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
35330 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
35340 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  on left-hand sid
35350 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20  e of constraint 
35360 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
35370 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20   char op;       
35380 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20    /* Constraint 
35390 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20  operator */.    
353a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75   unsigned char u
353b0 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72  sable;     /* Tr
353c0 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74  ue if this const
353d0 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20  raint is usable 
353e0 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72  */.     int iTer
353f0 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20  mOffset;        
35400 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
35410 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65  ally - xBestInde
35420 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20  x should ignore 
35430 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
35440 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20  int;            
35450 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52  /* Table of WHER
35460 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
35470 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f  ints */.  int nO
35480 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
35490 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
354a0 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f  f terms in the O
354b0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
354c0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
354d0 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
354e0 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
354f0 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
35500 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
35510 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
35520 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
35530 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
35540 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
35550 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61  r ASC. */.  } *a
35560 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
35570 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
35580 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
35590 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
355a0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
355b0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
355c0 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
355d0 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
355e0 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
355f0 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
35600 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
35610 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
35620 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
35630 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
35640 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
35650 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
35660 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
35670 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
35680 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
35690 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
356a0 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
356b0 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
356c0 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
356d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
356e0 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
356f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
35700 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
35710 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
35720 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
35730 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
35740 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
35750 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
35760 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
35770 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
35780 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
35790 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
357a0 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
357b0 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
357c0 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
357d0 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
357e0 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  index */.};../*.
357f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
35800 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74  tual Table Const
35810 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43  raint Operator C
35820 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
35830 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20   macros defined 
35840 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  the allowed valu
35850 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73  es for the.** [s
35860 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
35870 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  o].aConstraint[]
35880 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68  .op field.  Each
35890 20 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74   value represent
358a0 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72  s.** an operator
358b0 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
358c0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65   a constraint te
358d0 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45 20  rm in the wHERE 
358e0 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71  clause of.** a q
358f0 75 65 72 79 20 74 68 61 74 20 75 73 65 73 20 61  uery that uses a
35900 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
35910 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
35920 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
35930 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
35940 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
35950 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
35960 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
35970 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
35980 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
35990 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
359a0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
359b0 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
359c0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
359d0 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
359e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
359f0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
35a00 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43  ATCH 64../*.** C
35a10 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
35a20 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
35a30 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
35a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
35a50 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
35a60 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65  to register a ne
35a70 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
35a80 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a   module] name..*
35a90 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20  * ^Module names 
35aa0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72  must be register
35ab0 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65  ed before.** cre
35ac0 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72  ating a new [vir
35ad0 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e  tual table] usin
35ae0 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64  g the module and
35af0 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a   before using a.
35b00 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b  ** preexisting [
35b10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66  virtual table] f
35b20 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
35b30 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65  *.** ^The module
35b40 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65   name is registe
35b50 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  red on the [data
35b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35b70 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
35b80 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
35b90 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65  eter.  ^The name
35ba0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
35bb0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a  s given by the .
35bc0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
35bd0 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64  ter.  ^The third
35be0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
35bf0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68  pointer to.** th
35c00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35c10 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
35c20 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
35c30 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a    ^The fourth.**
35c40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
35c50 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e   arbitrary clien
35c60 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  t data pointer t
35c70 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68  hat is passed th
35c80 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68  rough.** into th
35c90 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20  e [xCreate] and 
35ca0 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f  [xConnect] metho
35cb0 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  ds of the virtua
35cc0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a  l table module.*
35cd0 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72  * when a new vir
35ce0 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65  tual table is be
35cf0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f   being created o
35d00 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e  r reinitialized.
35d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35d20 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
35d30 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
35d40 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72   has a fifth par
35d50 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
35d60 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
35d70 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
35d80 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
35d90 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a  .  ^SQLite will.
35da0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ** invoke the de
35db0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
35dc0 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20  n (if it is not 
35dd0 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74  NULL) when SQLit
35de0 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  e.** no longer n
35df0 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74  eeds the pClient
35e00 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e  Data pointer.  ^
35e10 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  The destructor w
35e20 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69  ill also.** be i
35e30 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
35e40 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  ll to sqlite3_cr
35e50 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
35e60 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20   fails..** ^The 
35e70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
35e80 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72  odule().** inter
35e90 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
35ea0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
35eb0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
35ec0 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20   with a NULL.** 
35ed0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69  destructor..*/.i
35ee0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
35ef0 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
35f00 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
35f10 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
35f20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
35f30 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
35f40 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
35f50 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
35f60 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
35f70 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
35f80 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
35f90 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
35fa0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
35fb0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
35fc0 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
35fd0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
35fe0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
35ff0 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e  Connect */.);.in
36000 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36010 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
36020 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36030 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
36040 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
36050 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
36060 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
36070 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
36080 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
36090 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
360a0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
360b0 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
360c0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
360d0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
360e0 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
360f0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
36100 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
36110 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
36120 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
36130 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
36140 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
36150 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
36160 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
36170 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
36180 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  tance Object.** 
36190 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
361a0 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65  3_vtab.**.** Eve
361b0 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
361c0 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
361d0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
361e0 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74  subclass.** of t
361f0 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65  his object to de
36200 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
36210 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
36220 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
36230 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
36240 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
36250 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
36260 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
36270 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
36280 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
36290 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
362a0 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
362b0 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
362c0 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
362d0 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
362e0 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
362f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
36300 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61  *.** ^Virtual ta
36310 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
36320 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
36330 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
36340 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
36350 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
36360 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
36370 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68   to zErrMsg.  Th
36380 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a  e method should.
36390 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61  ** take care tha
363a0 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69  t any prior stri
363b0 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61  ng is freed by a
363c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
363d0 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69  3_free()].** pri
363e0 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
363f0 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
36400 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72  zErrMsg.  ^After
36410 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
36420 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
36430 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
36440 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
36450 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
36460 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
36470 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
36480 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
36490 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
364a0 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
364b0 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  d..*/.struct sql
364c0 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
364d0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
364e0 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
364f0 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
36500 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
36510 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
36520 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
36530 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f          /* NO LO
36540 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63  NGER USED */.  c
36550 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
36560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36570 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
36580 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
36590 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
365a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
365b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
365c0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
365d0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
365e0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
365f0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
36600 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
36610 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
36620 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
36630 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
36640 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a  able cursor}.**.
36650 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
36660 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
36670 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
36680 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
36690 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
366a0 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
366b0 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
366c0 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
366d0 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
366e0 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
366f0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
36700 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
36710 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
36720 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
36730 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
36740 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
36750 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
36760 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
36770 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
36780 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
36790 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
367a0 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
367b0 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61  thod.  Cursors a
367c0 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
367d0 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
367e0 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
367f0 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
36800 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
36810 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
36820 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
36830 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
36840 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
36850 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
36860 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
36870 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
36880 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
36890 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
368a0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
368b0 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
368c0 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
368d0 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
368e0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
368f0 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
36900 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
36910 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
36920 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
36930 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
36940 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
36950 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
36960 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
36970 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
36980 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
36990 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
369a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
369b0 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
369c0 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
369d0 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  l Table.**.** ^T
369e0 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
369f0 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
36a00 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72  ods of a.** [vir
36a10 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
36a20 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74  e] call this int
36a30 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63  erface.** to dec
36a40 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
36a50 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
36a60 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
36a70 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
36a80 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
36a90 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
36aa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36ab0 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
36ac0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
36ad0 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a  ar *zSQL);../*.*
36ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72  * CAPI3REF: Over
36af0 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20  load A Function 
36b00 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  For A Virtual Ta
36b10 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74  ble.**.** ^(Virt
36b20 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
36b30 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
36b40 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
36b50 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
36b60 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46  ** using the [xF
36b70 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74  indFunction] met
36b80 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74  hod of the [virt
36b90 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
36ba0 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62  ].  .** But glob
36bb0 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
36bc0 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
36bd0 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
36be0 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
36bf0 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  loaded.)^.**.** 
36c00 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73  ^(This API makes
36c10 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76   sure a global v
36c20 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63  ersion of a func
36c30 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74  tion with a part
36c40 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61  icular.** name a
36c50 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  nd number of par
36c60 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20  ameters exists. 
36c70 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63   If no such func
36c80 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62  tion exists.** b
36c90 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69  efore this API i
36ca0 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20  s called, a new 
36cb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61  function is crea
36cc0 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70  ted.)^  ^The imp
36cd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
36ce0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
36cf0 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
36d00 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
36d10 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
36d20 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
36d30 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
36d40 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
36d50 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
36d60 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
36d70 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
36d80 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
36d90 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
36da0 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72  ded.** by a [vir
36db0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
36dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
36dd0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
36de0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
36df0 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
36e00 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
36e10 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
36e20 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
36e30 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
36e40 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
36e50 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
36e60 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
36e70 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
36e80 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
36e90 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
36ea0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
36eb0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
36ec0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
36ed0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
36ee0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
36ef0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
36f00 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
36f10 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
36f20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
36f30 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
36f40 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
36f50 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
36f60 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
36f70 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
36f80 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
36f90 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
36fa0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
36fb0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
36fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
36fd0 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
36fe0 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f  en BLOB.** KEYWO
36ff0 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
37000 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
37010 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
37020 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
37030 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
37040 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
37050 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
37060 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
37070 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
37080 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
37090 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20  ed..** ^Objects 
370a0 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65  of this type are
370b0 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
370c0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
370d0 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79  ].** and destroy
370e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
370f0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  lob_close()]..**
37100 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
37110 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
37120 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
37130 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
37140 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
37150 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
37160 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
37170 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
37180 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
37190 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
371a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
371b0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
371c0 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  e BLOB in bytes.
371d0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
371e0 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
371f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
37200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
37210 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
37220 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a  ncremental I/O.*
37230 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
37240 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b  rfaces opens a [
37250 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61  BLOB handle | ha
37260 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f  ndle] to the BLO
37270 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20  B located.** in 
37280 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e  row iRow, column
37290 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
372a0 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
372b0 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
372c0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
372d0 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f  ame BLOB that wo
372e0 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
372f0 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
37300 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
37310 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
37320 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77  Table WHERE [row
37330 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  id] = iRow;.** <
37340 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  /pre>)^.**.** ^I
37350 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
37360 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
37370 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  o, then the BLOB
37380 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
37390 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65  ead.** and write
373a0 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20   access. ^If it 
373b0 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
373c0 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
373d0 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20  read access..** 
373e0 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  ^It is not possi
373f0 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
37400 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
37410 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72  t of an index or
37420 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79   primary .** key
37430 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49   for writing. ^I
37440 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  f [foreign key c
37450 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20  onstraints] are 
37460 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a  enabled, it is .
37470 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
37480 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
37490 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
374a0 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66   a [child key] f
374b0 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a  or writing..**.*
374c0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
374d0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
374e0 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
374f0 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
37500 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
37510 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
37520 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
37530 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
37540 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66  at.** appears af
37550 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
37560 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  rd when the data
37570 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
37580 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
37590 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61  ..** ^For the ma
375a0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
375b0 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
375c0 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a  ame is "main"..*
375d0 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  * ^For TEMP tabl
375e0 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
375f0 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
37600 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
37610 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
37620 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
37630 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
37640 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
37650 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
37660 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
37670 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
37680 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c  turned and *ppBl
37690 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  ob is set.** to 
376a0 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  be a null pointe
376b0 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75  r.)^.** ^This fu
376c0 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
376d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
376e0 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
376f0 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
37700 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
37710 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
37720 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37730 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65  errmsg()] and re
37740 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  lated.** functio
37750 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  ns. ^Note that t
37760 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61  he *ppBlob varia
37770 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ble is always in
37780 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a  itialized in a.*
37790 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  * way that makes
377a0 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f   it safe to invo
377b0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ke [sqlite3_blob
377c0 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70  _close()] on *pp
377d0 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65  Blob.** regardle
377e0 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
377f0 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  s or failure of 
37800 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
37810 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77  .** ^(If the row
37820 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
37830 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
37840 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
37850 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
37860 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
37870 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
37880 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
37890 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
378a0 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
378b0 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
378c0 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
378d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
378e0 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
378f0 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
37900 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
37910 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
37920 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a   is open on.)^.*
37930 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  * ^Calls to [sql
37940 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
37950 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
37960 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
37970 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
37980 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
37990 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
379a0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
379b0 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67  ORT]..** ^(Chang
379c0 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  es written into 
379d0 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20  a BLOB prior to 
379e0 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e  the BLOB expirin
379f0 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c  g are not.** rol
37a00 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20  led back by the 
37a10 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
37a20 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68  e BLOB.  Such ch
37a30 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74  anges will event
37a40 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20  ually.** commit 
37a50 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  if the transacti
37a60 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  on continues to 
37a70 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a  completion.)^.**
37a80 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71  .** ^Use the [sq
37a90 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
37aa0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
37ab0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
37ac0 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  ize of.** the op
37ad0 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65  ened blob.  ^The
37ae0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
37af0 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67  may not be chang
37b00 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e  ed by this.** in
37b10 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68  terface.  Use th
37b20 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63  e [UPDATE] SQL c
37b30 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65  ommand to change
37b40 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a   the size of a.*
37b50 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54  * blob..**.** ^T
37b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
37b70 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64  _zeroblob()] and
37b80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
37b90 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74  _zeroblob()] int
37ba0 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74  erfaces.** and t
37bb0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72  he built-in [zer
37bc0 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74  oblob] SQL funct
37bd0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c  ion can be used,
37be0 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20   if desired,.** 
37bf0 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70  to create an emp
37c00 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20  ty, zero-filled 
37c10 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f  blob in which to
37c20 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75   read or write u
37c30 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74  sing.** this int
37c40 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f  erface..**.** To
37c50 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63   avoid a resourc
37c60 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70  e leak, every op
37c70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
37c80 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c   should eventual
37c90 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65  ly.** be release
37ca0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
37cb0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
37cc0 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
37cd0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
37ce0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
37cf0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
37d00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
37d10 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
37d20 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
37d30 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
37d40 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
37d50 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
37d60 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
37d70 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 6f 76 65  * CAPI3REF: Move
37d80 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74   a BLOB Handle t
37d90 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a  o a New Row.**.*
37da0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
37db0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 6f 76 65   is used to move
37dc0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f   an existing blo
37dd0 62 20 68 61 6e 64 6c 65 20 73 6f 20 74 68 61 74  b handle so that
37de0 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f   it points.** to
37df0 20 61 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77   a different row
37e00 20 6f 66 20 74 68 65 20 73 61 6d 65 20 64 61 74   of the same dat
37e10 61 62 61 73 65 20 74 61 62 6c 65 2e 20 5e 54 68  abase table. ^Th
37e20 65 20 6e 65 77 20 72 6f 77 20 69 73 20 69 64 65  e new row is ide
37e30 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ntified.** by th
37e40 65 20 72 6f 77 69 64 20 76 61 6c 75 65 20 70 61  e rowid value pa
37e50 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
37e60 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c  nd argument. Onl
37e70 79 20 74 68 65 20 72 6f 77 20 63 61 6e 20 62 65  y the row can be
37e80 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20 5e 54 68  .** changed. ^Th
37e90 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
37ea0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20  e and column on 
37eb0 77 68 69 63 68 20 74 68 65 20 62 6c 6f 62 20 68  which the blob h
37ec0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a  andle is open.**
37ed0 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
37ee0 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65 78 69 73  . Moving an exis
37ef0 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ting blob handle
37f00 20 74 6f 20 61 20 6e 65 77 20 72 6f 77 20 63 61   to a new row ca
37f10 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65 72 20 74  n be.** faster t
37f20 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  han closing the 
37f30 65 78 69 73 74 69 6e 67 20 68 61 6e 64 6c 65 20  existing handle 
37f40 61 6e 64 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65  and opening a ne
37f50 77 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  w one..**.** ^(T
37f60 68 65 20 6e 65 77 20 72 6f 77 20 6d 75 73 74 20  he new row must 
37f70 6d 65 65 74 20 74 68 65 20 73 61 6d 65 20 63 72  meet the same cr
37f80 69 74 65 72 69 61 20 61 73 20 66 6f 72 20 5b 73  iteria as for [s
37f90 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
37fa0 28 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d 75 73 74  ()] -.** it must
37fb0 20 65 78 69 73 74 20 61 6e 64 20 74 68 65 72 65   exist and there
37fc0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
37fd0 61 20 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76  a blob or text v
37fe0 61 6c 75 65 20 73 74 6f 72 65 64 20 69 6e 0a 2a  alue stored in.*
37ff0 2a 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  * the nominated 
38000 63 6f 6c 75 6d 6e 2e 29 5e 20 5e 49 66 20 74 68  column.)^ ^If th
38010 65 20 6e 65 77 20 72 6f 77 20 69 73 20 6e 6f 74  e new row is not
38020 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20   present in the 
38030 74 61 62 6c 65 2c 20 6f 72 20 69 66 0a 2a 2a 20  table, or if.** 
38040 69 74 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6e 74  it does not cont
38050 61 69 6e 20 61 20 62 6c 6f 62 20 6f 72 20 74 65  ain a blob or te
38060 78 74 20 76 61 6c 75 65 2c 20 6f 72 20 69 66 20  xt value, or if 
38070 61 6e 6f 74 68 65 72 20 65 72 72 6f 72 20 6f 63  another error oc
38080 63 75 72 73 2c 20 61 6e 0a 2a 2a 20 53 51 4c 69  curs, an.** SQLi
38090 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  te error code is
380a0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
380b0 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73  e blob handle is
380c0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 62 6f 72   considered abor
380d0 74 65 64 2e 0a 2a 2a 20 5e 41 6c 6c 20 73 75 62  ted..** ^All sub
380e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
380f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
38100 65 61 64 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ead()], [sqlite3
38110 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 6f  _blob_write()] o
38120 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  r.** [sqlite3_bl
38130 6f 62 5f 72 65 6f 70 65 6e 28 29 5d 20 6f 6e 20  ob_reopen()] on 
38140 61 6e 20 61 62 6f 72 74 65 64 20 62 6c 6f 62 20  an aborted blob 
38150 68 61 6e 64 6c 65 20 69 6d 6d 65 64 69 61 74 65  handle immediate
38160 6c 79 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ly return.** SQL
38170 49 54 45 5f 41 42 4f 52 54 2e 20 5e 43 61 6c 6c  ITE_ABORT. ^Call
38180 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  ing [sqlite3_blo
38190 62 5f 62 79 74 65 73 28 29 5d 20 6f 6e 20 61 6e  b_bytes()] on an
381a0 20 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 61   aborted blob ha
381b0 6e 64 6c 65 0a 2a 2a 20 61 6c 77 61 79 73 20 72  ndle.** always r
381c0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
381d0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
381e0 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62  n sets the datab
381f0 61 73 65 20 68 61 6e 64 6c 65 20 65 72 72 6f 72  ase handle error
38200 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
38210 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  e..*/.SQLITE_EXP
38220 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
38230 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65  lite3_blob_reope
38240 6e 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  n(sqlite3_blob *
38250 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
38260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38270 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  F: Close A BLOB 
38280 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c  Handle.**.** ^Cl
38290 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  oses an open [BL
382a0 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a  OB handle]..**.*
382b0 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  * ^Closing a BLO
382c0 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
382d0 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
382e0 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
382f0 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
38300 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
38310 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
38320 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
38330 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
38340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
38350 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74  s in [autocommit
38360 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61   mode]..** ^If a
38370 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d  ny writes were m
38380 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c  ade to the BLOB,
38390 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68   they might be h
383a0 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20  eld in cache.** 
383b0 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20  until the close 
383c0 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65  operation if the
383d0 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a  y will fit..**.*
383e0 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20  * ^(Closing the 
383f0 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65  BLOB often force
38400 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a  s the changes.**
38410 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64   out to disk and
38420 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65   so if any I/O e
38430 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65  rrors occur, the
38440 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63  y will likely oc
38450 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69  cur.** at the ti
38460 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42  me when the BLOB
38470 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79   is closed.  Any
38480 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
38490 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
384a0 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
384b0 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
384c0 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a  return value.)^.
384d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42  **.** ^(The BLOB
384e0 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e   is closed uncon
384f0 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65  ditionally.  Eve
38500 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e  n if this routin
38510 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20  e returns.** an 
38520 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20  error code, the 
38530 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c  BLOB is still cl
38540 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  osed.)^.**.** ^C
38550 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
38560 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20  ine with a null 
38570 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73  pointer (such as
38580 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e   would be return
38590 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65  ed.** by a faile
385a0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
385b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29  e3_blob_open()])
385c0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
385d0 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  o-op..*/.int sql
385e0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
385f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
38600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38610 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a  : Return The Siz
38620 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
38630 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73  B.**.** ^Returns
38640 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
38650 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61  es of the BLOB a
38660 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
38670 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  e .** successful
38680 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20  ly opened [BLOB 
38690 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f  handle] in its o
386a0 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  nly argument.  ^
386b0 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74  The.** increment
386c0 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74  al blob I/O rout
386d0 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65  ines can only re
386e0 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e  ad or overwritin
386f0 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c  g existing.** bl
38700 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79  ob content; they
38710 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
38720 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
38730 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  b..**.** This ro
38740 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
38750 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
38760 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
38770 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
38780 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
38790 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
387a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
387b0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
387c0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
387d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
387e0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
387f0 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
38800 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
38810 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
38820 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
38830 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
38840 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
38850 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  avior..*/.int sq
38860 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
38870 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
38880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38890 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f  F: Read Data Fro
388a0 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  m A BLOB Increme
388b0 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54  ntally.**.** ^(T
388c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
388d0 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
388e0 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b  a from an open