/ Hex Artifact Content
Login

Artifact 369c767e6b9f101d63d8e4c5e40279f975ccec08:


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 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
a170: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
a180: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
a190: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
a1a0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
a1b0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
a1c0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
a1d0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
a1e0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
a1f0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
a200: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
a210: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
a220: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
a230: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
a240: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
a250: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
a260: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
a270: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
a280: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
a290: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
a2a0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
a2b0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
a2c0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
a2d0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
a2e0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
a2f0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
a300: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
a310: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
a320: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
a330: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
a340: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
a350: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
a360: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
a370: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
a380: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
a390: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
a3a0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
a3b0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
a3c0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
a3d0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
a3e0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
a3f0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
a400: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
a410: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
a420: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
a430: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
a440: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
a450: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
a460: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
a470: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
a480: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
a490: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a4a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
a4b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
a4c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
a4d0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
a4e0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
a4f0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
a500: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
a510: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
a520: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
a530: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
a540: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
a550: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
a560: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
a570: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
a580: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
a590: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
a5a0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
a5b0: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
a5c0: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
a5d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
a5e0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
a5f0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
a600: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
a610: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
a620: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
a630: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
a640: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
a650: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
a660: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
a670: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a680: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
a690: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
a6a0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
a6b0: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
a6c0: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
a6d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a6e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a6f0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
a700: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
a710: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a720: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a730: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
a740: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
a750: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
a760: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a770: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
a780: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
a790: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
a7a0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
a7b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
a7c0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
a7d0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
a7e0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
a7f0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
a800: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
a810: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
a820: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
a830: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
a840: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
a850: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
a860: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
a870: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
a880: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
a890: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a8a0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
a8b0: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
a8c0: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
a8d0: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
a8e0: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
a8f0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
a900: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
a910: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
a920: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
a930: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
a940: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
a950: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
a960: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
a970: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
a980: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
a990: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
a9a0: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
a9b0: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
a9c0: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
a9d0: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
a9e0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
a9f0: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
aa00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
aa10: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
aa20: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
aa30: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
aa40: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
aa50: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
aa60: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
aa70: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
aa80: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
aa90: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
aaa0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
aab0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
aac0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 76  t char *zName, v
aad0: 6f 69 64 20 2a 70 46 75 6e 63 29 3b 0a 20 20 76  oid *pFunc);.  v
aae0: 6f 69 64 20 2a 28 2a 78 47 65 74 53 79 73 74 65  oid *(*xGetSyste
aaf0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ab00: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ab10: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
ab20: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
ab30: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ab40: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ab50: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
ab60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
ab70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ab80: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
ab90: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
aba0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
abb0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
abc0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
abd0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
abe0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
abf0: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
ac00: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
ac10: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
ac20: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
ac30: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
ac40: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
ac50: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ac60: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ac70: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
ac80: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
ac90: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
aca0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
acb0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
acc0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
acd0: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
ace0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
acf0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
ad00: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ad10: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
ad20: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ad30: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
ad40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ad50: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
ad60: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
ad70: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
ad80: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ad90: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
ada0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
adb0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
adc0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
add0: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
ade0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
adf0: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
ae00: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
ae10: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
ae20: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
ae30: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
ae40: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
ae50: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
ae60: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
ae70: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ae80: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ae90: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
aea0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
aeb0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
aec0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
aed0: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
aee0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
aef0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
af00: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
af10: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
af20: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
af30: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
af40: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
af50: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
af60: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
af70: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
af80: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
af90: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
afa0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
afb0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
afc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
afd0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
afe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
aff0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
b000: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
b010: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
b020: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
b030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
b040: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
b050: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
b060: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b070: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
b080: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
b090: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
b0a0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
b0b0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
b0c0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
b0d0: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
b0e0: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
b0f0: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
b100: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
b110: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
b120: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
b130: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
b140: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
b150: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
b160: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
b170: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
b180: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
b190: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
b1a0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
b1b0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
b1c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
b1d0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
b1e0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
b1f0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
b200: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
b210: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
b220: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
b230: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
b240: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
b250: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
b260: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
b270: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
b280: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
b290: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
b2a0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
b2b0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
b2c0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
b2d0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
b2e0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
b2f0: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
b300: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
b310: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
b320: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
b330: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
b340: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
b350: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b360: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
b370: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
b380: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
b390: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
b3a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
b3b0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
b3c0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
b3d0: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
b3e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
b3f0: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
b400: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
b410: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
b420: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
b430: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
b440: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
b450: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
b460: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
b470: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
b480: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
b490: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
b4a0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
b4b0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
b4c0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
b4d0: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
b4e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b4f0: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
b500: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
b510: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
b520: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
b530: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
b540: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b550: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
b560: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
b570: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
b580: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
b590: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
b5a0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
b5b0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
b5c0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
b5d0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
b5e0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
b5f0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
b600: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
b610: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
b620: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
b630: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
b640: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
b650: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
b660: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
b670: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
b680: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
b690: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
b6a0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
b6b0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
b6c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b6d0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
b6e0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
b6f0: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
b700: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
b710: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
b720: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
b730: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
b740: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
b750: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
b760: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
b770: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
b780: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
b790: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
b7a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b7b0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
b7c0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
b7d0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
b7e0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
b7f0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
b800: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
b810: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
b820: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
b830: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
b840: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
b850: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
b860: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
b870: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
b880: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
b890: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
b8a0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
b8b0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
b8c0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
b8d0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
b8e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
b8f0: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
b900: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
b910: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
b920: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
b930: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
b940: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
b950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
b960: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b970: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
b980: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
b990: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
b9a0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
b9b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b9c0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
b9d0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
b9e0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
b9f0: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
ba00: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
ba10: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
ba20: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
ba30: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
ba40: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
ba50: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
ba60: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
ba70: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
ba80: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
ba90: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
baa0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
bab0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
bac0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
bad0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
bae0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
baf0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
bb00: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
bb10: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
bb20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
bb30: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
bb40: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
bb50: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
bb60: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
bb70: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
bb80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bb90: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
bba0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
bbb0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
bbc0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
bbd0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
bbe0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
bbf0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
bc00: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
bc10: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
bc20: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
bc30: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
bc40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bc50: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
bc60: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
bc70: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
bc80: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
bc90: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
bca0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
bcb0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
bcc0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
bcd0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bce0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
bcf0: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
bd00: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
bd10: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
bd20: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
bd30: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
bd40: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
bd50: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
bd60: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
bd70: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
bd80: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
bd90: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
bda0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
bdb0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
bdc0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
bdd0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
bde0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
bdf0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
be00: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
be10: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
be20: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
be30: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
be40: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
be50: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
be60: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
be70: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
be80: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
be90: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
bea0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
beb0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
bec0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
bed0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
bee0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
bef0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
bf00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bf10: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
bf20: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
bf30: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
bf40: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
bf50: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
bf60: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
bf70: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
bf80: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
bf90: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
bfa0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
bfb0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
bfc0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
bfd0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
bfe0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
bff0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
c000: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
c010: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
c020: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
c030: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
c040: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
c050: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
c060: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
c070: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
c080: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
c090: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
c0a0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
c0b0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
c0c0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
c0d0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
c0e0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
c0f0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
c100: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
c110: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
c120: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
c130: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
c140: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
c150: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
c160: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
c170: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
c180: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
c190: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
c1a0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
c1b0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
c1c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c1d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
c1e0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c1f0: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
c200: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
c210: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
c220: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
c230: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
c240: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
c250: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
c260: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c270: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
c280: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
c290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c2a0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
c2b0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
c2c0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
c2d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c2e0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
c2f0: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
c300: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
c310: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
c320: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
c330: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
c340: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
c350: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
c360: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
c370: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
c380: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
c390: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
c3a0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
c3b0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
c3c0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
c3d0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
c3e0: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
c3f0: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
c400: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
c410: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
c420: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
c430: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
c440: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c450: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
c460: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
c470: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
c480: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
c490: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
c4a0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
c4b0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
c4c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
c4d0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
c4e0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
c4f0: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
c500: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
c510: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
c520: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
c530: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c540: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
c550: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
c560: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
c570: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
c580: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
c590: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
c5a0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
c5b0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
c5c0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
c5d0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
c5e0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
c5f0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
c600: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
c610: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
c620: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
c630: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
c640: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
c650: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
c660: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
c670: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
c680: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
c690: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
c6a0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
c6b0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
c6c0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
c6d0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
c6e0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
c6f0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
c700: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
c710: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
c720: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
c730: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
c740: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
c750: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
c760: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
c770: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
c780: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
c790: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
c7a0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
c7b0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
c7c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
c7d0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
c7e0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
c7f0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
c800: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
c810: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
c820: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
c830: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
c840: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c850: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
c860: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
c870: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
c880: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
c890: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
c8a0: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
c8b0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
c8c0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
c8d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
c8e0: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
c8f0: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
c900: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
c910: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
c920: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
c930: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
c940: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
c950: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
c960: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
c970: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
c980: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
c990: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
c9a0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
c9b0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
c9c0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
c9d0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c9e0: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
c9f0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
ca00: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
ca10: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
ca20: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
ca30: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
ca40: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
ca50: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
ca60: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49  ing on the [SQLI
ca70: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
ca80: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
ca90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
caa0: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
cab0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
cac0: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
cad0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
cae0: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
caf0: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
cb00: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
cb10: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
cb20: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
cb30: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
cb40: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
cb50: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
cb60: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
cb70: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
cb80: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
cb90: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
cba0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
cbb0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
cbc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cbd0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
cbe0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cbf0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
cc00: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
cc10: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
cc20: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
cc30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
cc40: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
cc50: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
cc60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
cc70: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
cc80: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
cc90: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
cca0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ccb0: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
ccc0: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
ccd0: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a  rgument).  The.*
cce0: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  * sqlite3_db_con
ccf0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
cd00: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75  should only be u
cd10: 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  sed immediately 
cd20: 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74  after.** the dat
cd30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cd40: 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
cd50: 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
cd60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
cd70: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
cd80: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
cd90: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].  .**.** The s
cda0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
cdb0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
cdc0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
cdd0: 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72   the.** configur
cde0: 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20  ation verb - an 
cdf0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
ce00: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
ce10: 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68  .** aspect of th
ce20: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ce30: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
ce40: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
ce50: 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20  The only choice 
ce60: 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69  for this value i
ce70: 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  s [SQLITE_DBCONF
ce80: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a  IG_LOOKASIDE]..*
ce90: 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20  * New verbs are 
cea0: 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64  likely to be add
ceb0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
cec0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
ced0: 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61  .** Additional a
cee0: 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20  rguments depend 
cef0: 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a  on the verb..**.
cf00: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
cf10: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
cf20: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
cf30: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
cf40: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
cf50: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
cf60: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
cf70: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cf80: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
cf90: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
cfa0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
cfb0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
cfc0: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
cfd0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
cfe0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
cff0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
d000: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
d010: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
d020: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
d030: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
d040: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
d050: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
d060: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
d070: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
d080: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
d090: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
d0a0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
d0b0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
d0c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d0d0: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
d0e0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d0f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
d100: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
d110: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d120: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
d130: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
d140: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
d150: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
d160: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
d170: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
d180: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d190: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
d1a0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
d1b0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
d1c0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
d1d0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
d1e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
d1f0: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
d200: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
d210: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
d220: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
d230: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
d240: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
d250: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
d260: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
d270: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
d280: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
d290: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
d2a0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
d2b0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
d2c0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
d2d0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
d2e0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
d2f0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
d300: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
d310: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
d320: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d330: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
d340: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
d350: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
d360: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
d370: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
d380: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
d390: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
d3a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
d3b0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
d3c0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
d3d0: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
d3e0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
d3f0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
d400: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
d410: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
d420: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
d430: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e  * The xMalloc an
d440: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
d450: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
d460: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61  he.** malloc() a
d470: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
d480: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
d490: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
d4a0: 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63  .** The xRealloc
d4b0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72   method must wor
d4c0: 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29  k like realloc()
d4d0: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
d4e0: 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20  rd C library.** 
d4f0: 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69  with the excepti
d500: 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73  on that if the s
d510: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
d520: 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65  o xRealloc is ze
d530: 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  ro,.** xRealloc 
d540: 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20  must be a no-op 
d550: 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65  - it must not pe
d560: 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61  rform any alloca
d570: 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c  tion or.** deall
d580: 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74  ocation.  ^SQLit
d590: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d5a0: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
d5b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
d5c0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
d5d0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d5e0: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
d5f0: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20  to xRoundup..** 
d600: 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20  And so in cases 
d610: 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61  where xRoundup a
d620: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
d630: 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c  positive number,
d640: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e  .** xRealloc can
d650: 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79   perform exactly
d660: 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64   as the standard
d670: 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63   library realloc
d680: 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20  () and.** still 
d690: 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65  be in compliance
d6a0: 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69   with this speci
d6b0: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  fication..**.** 
d6c0: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
d6d0: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
d6e0: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
d6f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
d700: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
d710: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
d720: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
d730: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
d740: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
d750: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
d760: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
d770: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
d780: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
d790: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
d7a0: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
d7b0: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
d7c0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
d7d0: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
d7e0: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
d7f0: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
d800: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
d810: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
d820: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
d830: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
d840: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
d850: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
d860: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
d870: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
d880: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
d890: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
d8a0: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
d8b0: 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
d8c0: 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
d8d0: 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
d8e0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
d8f0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
d900: 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
d910: 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
d920: 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
d930: 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
d940: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
d950: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
d960: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
d970: 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
d980: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
d990: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
d9a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
d9b0: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
d9c0: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
d9d0: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
d9e0: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
d9f0: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
da00: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
da10: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
da20: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
da30: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
da40: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
da50: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
da60: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
da70: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
da80: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
da90: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
daa0: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
dab0: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
dac0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
dad0: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
dae0: 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
daf0: 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
db00: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
db10: 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
db20: 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
db30: 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
db40: 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
db50: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
db60: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
db70: 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
db80: 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
db90: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
dba0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dbb0: 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
dbc0: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
dbd0: 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
dbe0: 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
dbf0: 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
dc00: 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
dc10: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
dc20: 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
dc30: 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
dc40: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
dc50: 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
dc60: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
dc70: 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
dc80: 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
dc90: 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
dca0: 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
dcb0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
dcc0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
dcd0: 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
dce0: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
dcf0: 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
dd00: 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
dd10: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
dd20: 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
dd30: 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
dd40: 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
dd50: 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
dd60: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
dd70: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
dd80: 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
dd90: 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
dda0: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
ddb0: 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
ddc0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
ddd0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
dde0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ddf0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
de00: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
de10: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
de20: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
de30: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
de40: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
de50: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
de60: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
de70: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
de80: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
de90: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
dea0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
deb0: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
dec0: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
ded0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
dee0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
def0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
df00: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
df10: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
df20: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
df30: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
df40: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
df50: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
df60: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
df70: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
df80: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
df90: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
dfa0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
dfb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
dfc0: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
dfd0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
dfe0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
dff0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
e000: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
e010: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
e020: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
e030: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
e040: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
e050: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
e060: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
e070: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
e080: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
e090: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
e0a0: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
e0b0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e0c0: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
e0d0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
e0e0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
e0f0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
e100: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
e110: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
e120: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e130: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
e140: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
e150: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
e160: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
e170: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
e180: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
e190: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
e1a0: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
e1b0: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
e1c0: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
e1d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
e1e0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
e1f0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
e200: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
e210: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
e220: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
e230: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
e240: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
e250: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
e260: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
e270: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e280: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
e290: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
e2a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e2b0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
e2c0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
e2d0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
e2e0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
e2f0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
e300: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
e310: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
e320: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
e330: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e340: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
e350: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
e360: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
e370: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
e380: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
e390: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
e3a0: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
e3b0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e3c0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e3d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e3e0: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
e3f0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
e400: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
e410: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
e420: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
e430: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
e440: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
e450: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
e460: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
e470: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
e480: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e490: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
e4a0: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
e4b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
e4c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
e4d0: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
e4e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e4f0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e500: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e510: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
e520: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
e530: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
e540: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
e550: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
e560: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
e570: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
e580: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
e590: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
e5a0: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
e5b0: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
e5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
e5d0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e5e0: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
e5f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e600: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
e610: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
e620: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
e630: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e640: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e650: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
e660: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
e670: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
e680: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
e690: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
e6a0: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
e6b0: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
e6c0: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
e6d0: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
e6e0: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
e6f0: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
e700: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e710: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
e720: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
e730: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e740: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e750: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e760: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e770: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e780: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e790: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e7a0: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
e7b0: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
e7c0: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
e7d0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e7e0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
e7f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
e800: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
e810: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
e820: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
e830: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e840: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
e850: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e860: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
e870: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
e880: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
e890: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
e8a0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
e8b0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
e8c0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
e8d0: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
e8e0: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
e8f0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
e900: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
e910: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
e920: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
e930: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
e940: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
e950: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
e960: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
e970: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
e980: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
e990: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
e9a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
e9b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
e9c0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
e9d0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
e9e0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
e9f0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
ea00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea10: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
ea20: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
ea30: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
ea40: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
ea50: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
ea60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ea70: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
ea80: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
ea90: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
eaa0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
eab0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
eac0: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
ead0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
eae0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
eaf0: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
eb00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
eb10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
eb20: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
eb30: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
eb40: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
eb50: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
eb60: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
eb70: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
eb80: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
eb90: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
eba0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
ebb0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
ebc0: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
ebd0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ebe0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ebf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ec00: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
ec10: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ec20: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ec30: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ec40: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ec50: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
ec60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
ec70: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
ec80: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
ec90: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
eca0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
ecb0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
ecc0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ecd0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
ece0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
ecf0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ed00: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
ed10: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
ed20: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
ed30: 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
ed40: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
ed50: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
ed60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ed70: 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
ed80: 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
ed90: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
eda0: 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
edb0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
edc0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
edd0: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
ede0: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
edf0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
ee00: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
ee10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
ee20: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
ee30: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
ee40: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
ee50: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ee60: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
ee70: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
ee80: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
ee90: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
eea0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
eeb0: 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
eec0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
eed0: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
eee0: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
eef0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef00: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
ef10: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
ef20: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
ef30: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ef40: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
ef50: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
ef60: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
ef70: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ef80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
ef90: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
efa0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
efb0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
efc0: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
efd0: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
efe0: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
eff0: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
f000: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f010: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
f020: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f030: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
f040: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
f050: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f060: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
f070: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
f080: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
f090: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
f0a0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
f0b0: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
f0c0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
f0d0: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
f0e0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
f0f0: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
f100: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f110: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
f120: 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
f130: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
f140: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
f150: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
f160: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f170: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
f180: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
f190: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
f1a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f1b0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
f1c0: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
f1d0: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
f1e0: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
f1f0: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
f200: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
f210: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
f220: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f230: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
f240: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f250: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f260: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f270: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f280: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f290: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
f2a0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
f2b0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
f2c0: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
f2d0: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
f2e0: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
f2f0: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68  which the scrach
f300: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
f310: 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
f320: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
f330: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
f340: 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
f350: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
f360: 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
f370: 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
f380: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
f390: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
f3a0: 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
f3b0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f3c0: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
f3d0: 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
f3e0: 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
f3f0: 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
f400: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
f410: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
f420: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
f430: 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
f440: 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
f450: 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
f460: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
f470: 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
f480: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
f490: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
f4a0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
f4b0: 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
f4c0: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
f4d0: 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
f4e0: 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
f4f0: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
f500: 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
f510: 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
f520: 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
f530: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
f540: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
f550: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
f560: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
f570: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
f580: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
f590: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
f5a0: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
f5b0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
f5c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f5d0: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
f5e0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
f5f0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
f600: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
f610: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
f620: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
f630: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
f640: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
f650: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
f660: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
f670: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
f680: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
f690: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
f6a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
f6b0: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
f6c0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
f6d0: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
f6e0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
f6f0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
f700: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
f710: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
f720: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
f730: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
f740: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
f750: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
f760: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
f770: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
f780: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
f790: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
f7a0: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
f7b0: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
f7c0: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
f7d0: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
f7e0: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
f7f0: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
f800: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
f810: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
f820: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
f830: 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
f840: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
f850: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
f860: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
f870: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
f880: 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
f890: 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
f8a0: 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
f8b0: 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
f8c0: 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
f8d0: 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
f8e0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
f8f0: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
f900: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
f910: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
f920: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
f930: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
f940: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
f950: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
f960: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
f970: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
f980: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
f990: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
f9a0: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
f9b0: 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
f9c0: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
f9d0: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
f9e0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
f9f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
fa00: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
fa10: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
fa20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
fa30: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
fa40: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
fa50: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
fa60: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
fa70: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
fa80: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
fa90: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
faa0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
fab0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
fac0: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
fad0: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
fae0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
faf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
fb00: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
fb10: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
fb20: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
fb30: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
fb40: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
fb50: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
fb60: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
fb70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
fb80: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
fb90: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
fba0: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
fbb0: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
fbc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
fbd0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
fbe0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
fbf0: 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
fc00: 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
fc10: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
fc20: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
fc30: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
fc40: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
fc50: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
fc60: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
fc70: 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
fc80: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
fc90: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
fca0: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
fcb0: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
fcc0: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
fcd0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
fce0: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
fcf0: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
fd00: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
fd10: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
fd20: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
fd30: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
fd40: 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
fd50: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
fd60: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
fd70: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
fd80: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
fd90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
fda0: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
fdb0: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
fdc0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
fdd0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
fde0: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
fdf0: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
fe00: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
fe10: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
fe20: 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
fe30: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
fe40: 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
fe50: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
fe60: 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
fe70: 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
fe80: 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
fe90: 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
fea0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
feb0: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
fec0: 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
fed0: 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c   2^12. Reasonabl
fee0: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
fef0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
ff00: 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
ff10: 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2e  2^5 through 2^8.
ff20: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ff30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
ff40: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
ff50: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ff60: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ff70: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ff80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ff90: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ffa0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ffb0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
ffc0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
ffd0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
ffe0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
fff0: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
10000 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
10010 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
10020 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
10030 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
10040 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
10050 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
10060 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
10070 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
10080 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
10090 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
100a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
100b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
100c0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
100d0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
100e0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
100f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10100 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10110 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10120 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10130 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
10140 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
10150 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
10160 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
10170 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
10180 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10190 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
101a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
101b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
101c0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
101d0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
101e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
101f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10200 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
10210 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
10220 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
10230 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
10240 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
10250 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
10260 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10270 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
10280 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
10290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
102a0 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
102b0 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
102c0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
102d0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
102e0 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
102f0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
10300 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
10310 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
10320 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
10330 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
10340 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
10350 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
10360 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
10370 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
10380 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
10390 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
103a0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
103b0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
103c0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
103d0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
103e0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
103f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
10400 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
10410 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
10420 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
10430 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
10440 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
10450 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10460 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
10470 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
10480 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
10490 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
104a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
104b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
104c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
104d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
104e0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
104f0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10500 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
10510 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
10520 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
10530 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10540 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
10550 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
10560 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
10570 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10580 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
10590 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
105a0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
105b0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
105c0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
105d0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
105e0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
105f0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
10600 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
10610 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
10620 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10630 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
10640 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
10650 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
10660 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10670 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
10680 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10690 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
106a0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
106b0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
106c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
106d0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
106e0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
106f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
10700 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64  CONFIG_PCACHE</d
10710 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10720 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10730 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10740 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10750 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
10760 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10770 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
10780 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
10790 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
107a0 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
107b0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
107c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
107d0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
107e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
107f0 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
10800 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
10810 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10820 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
10830 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10840 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e  G_GETPCACHE</dt>
10850 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
10860 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
10870 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
10880 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
10890 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
108a0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
108b0 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
108c0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
108d0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
108e0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
108f0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
10900 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
10910 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
10920 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
10930 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
10940 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
10950 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
10960 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
10970 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
10980 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
10990 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
109a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
109b0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
109c0 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
109d0 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
109e0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
109f0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
10a00 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
10a10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
10a20 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
10a30 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
10a40 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
10a50 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
10a60 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
10a70 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
10a80 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
10a90 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
10aa0 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
10ab0 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
10ac0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
10ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
10ae0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
10af0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
10b00 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
10b10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
10b20 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
10b30 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
10b40 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
10b50 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
10b60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
10b70 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
10b80 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
10b90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
10ba0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
10bb0 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
10bc0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
10bd0 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
10be0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
10bf0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
10c00 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
10c10 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
10c20 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
10c30 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
10c40 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
10c50 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
10c60 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
10c70 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
10c80 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
10c90 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
10ca0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
10cb0 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
10cc0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
10cd0 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
10ce0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10cf0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
10d00 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
10d10 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
10d20 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
10d30 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
10d40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
10d50 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
10d60 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
10d70 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
10d80 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
10d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10da0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
10db0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
10dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10dd0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10de0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
10df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10e00 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
10e10 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
10e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10e30 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
10e40 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
10e50 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
10e60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10e70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
10e80 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
10e90 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
10ea0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
10eb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
10ec0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
10ed0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
10ee0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
10ef0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
10f00 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
10f10 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
10f20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
10f30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
10f40 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
10f50 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
10f60 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
10f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10f80 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
10f90 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
10fa0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
10fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
10fc0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
10fd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
10fe0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10ff0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11000 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
11010 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
11020 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
11030 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
11040 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
11050 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
11060 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
11070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11080 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11090 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
110a0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
110b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
110c0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
110d0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
110e0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
110f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11100 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
11110 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
11120 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
11130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11140 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
11150 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
11160 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  void* */../*.** 
11170 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
11180 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
11190 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
111a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
111b0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
111c0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
111d0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
111e0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
111f0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
11200 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
11210 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
11220 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11230 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11240 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11250 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11260 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11270 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11280 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11290 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
112a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
112b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
112c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
112d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
112e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
112f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
11300 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
11310 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
11320 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
11330 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
11340 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
11350 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11360 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
11370 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
11380 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
11390 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
113a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
113b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
113c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
113d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
113e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
113f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11400 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11410 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
11420 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
11430 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
11440 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
11450 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
11460 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
11470 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
11480 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
11490 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
114a0 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
114b0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
114c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
114d0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
114e0 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75   to an memory bu
114f0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
11500 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
11510 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
11520 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
11530 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
11540 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
11550 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
11560 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
11570 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
11580 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
11590 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
115a0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
115b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
115c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
115d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
115e0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
115f0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
11600 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
11610 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
11620 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
11630 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
11640 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
11650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11660 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
11670 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
11680 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
11690 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
116a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
116b0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
116c0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
116d0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
116e0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
116f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11700 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
11710 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11720 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
11730 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
11740 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
11750 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
11760 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
11770 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
11780 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
11790 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
117a0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
117b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
117c0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
117d0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
117e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
117f0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
11800 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
11810 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
11820 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
11830 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
11840 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
11850 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
11860 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
11870 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
11880 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
11890 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
118a0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
118b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
118c0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
118d0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
118e0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
118f0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
11900 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
11910 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
11920 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
11930 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  ^</dd>.**.** </d
11940 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
11950 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11960 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20  OKASIDE    1001 
11970 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
11980 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t */.../*.** CAP
11990 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
119a0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
119b0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
119c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
119d0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
119e0 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
119f0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
11a00 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
11a10 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
11a20 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
11a30 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
11a40 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
11a50 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
11a60 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
11a70 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
11a80 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
11a90 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
11aa0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
11ab0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
11ac0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
11ad0 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
11ae0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
11af0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
11b00 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
11b10 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
11b20 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
11b30 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
11b40 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
11b50 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
11b60 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
11b70 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
11b80 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
11b90 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
11ba0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
11bb0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
11bc0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
11bd0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
11be0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
11bf0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
11c00 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
11c10 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
11c20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
11c30 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
11c40 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
11c50 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
11c60 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
11c70 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
11c80 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
11c90 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
11ca0 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
11cb0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
11cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
11cd0 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
11ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
11cf0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11d00 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73  ument.  ^If no s
11d10 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
11d20 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
11d30 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
11d40 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
11d50 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
11d60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
11d70 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
11d80 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
11d90 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
11da0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
11db0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
11dc0 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
11dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
11de0 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
11df0 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
11e00 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
11e10 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
11e20 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
11e30 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
11e40 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
11e50 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
11e60 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
11e70 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
11e80 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  fired.)^.**.** ^
11e90 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
11ea0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
11eb0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
11ec0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
11ed0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
11ee0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
11ef0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
11f00 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
11f10 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
11f20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
11f30 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
11f40 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
11f50 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
11f60 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
11f70 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
11f80 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
11f90 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
11fa0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
11fb0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
11fc0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
11fd0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
11fe0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
11ff0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
12000 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
12010 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
12020 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
12030 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
12040 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
12050 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
12060 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
12070 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
12080 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
12090 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
120a0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
120b0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
120c0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
120d0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
120e0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
120f0 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
12100 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
12110 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
12120 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
12130 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
12140 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
12150 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
12160 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
12170 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
12180 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
12190 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
121a0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
121b0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
121c0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
121d0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
121e0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
121f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12200 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
12210 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
12220 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
12230 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
12240 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
12250 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
12260 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
12270 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
12280 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
12290 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
122a0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
122b0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
122c0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
122d0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
122e0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
122f0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
12300 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
12310 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
12320 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
12330 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12340 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
12350 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
12360 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
12370 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
12380 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
12390 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
123a0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
123b0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
123c0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
123d0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
123e0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
123f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
12400 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
12410 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
12420 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
12430 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
12440 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
12450 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
12460 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
12470 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
12480 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
12490 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
124a0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
124b0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
124c0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
124d0 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
124e0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
124f0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
12500 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
12510 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
12520 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
12530 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
12540 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
12550 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
12560 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
12570 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
12580 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
12590 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
125a0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
125b0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
125c0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
125d0 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
125e0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
125f0 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
12600 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
12610 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
12620 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
12630 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
12640 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
12650 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
12660 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
12670 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
12680 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
12690 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
126a0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
126b0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
126c0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
126d0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
126e0 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
126f0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
12700 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
12710 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
12720 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
12730 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
12740 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
12750 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
12760 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
12770 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
12780 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
12790 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
127a0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
127b0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
127c0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
127d0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
127e0 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
127f0 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
12800 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
12810 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
12820 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
12830 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
12840 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
12850 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
12860 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
12870 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
12880 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
12890 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
128a0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
128b0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
128c0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
128d0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
128e0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
128f0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
12900 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
12910 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
12920 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
12930 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
12940 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
12950 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
12960 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
12970 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
12980 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
12990 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
129a0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
129b0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
129c0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
129d0 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
129e0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
129f0 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
12a00 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
12a10 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
12a20 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
12a30 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
12a40 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
12a50 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
12a60 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
12a70 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
12a80 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
12a90 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
12aa0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
12ab0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
12ac0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
12ad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
12ae0 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
12af0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
12b00 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
12b10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
12b20 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
12b30 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
12b40 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
12b50 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
12b60 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
12b70 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
12b80 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
12b90 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
12ba0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
12bb0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
12bc0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
12bd0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
12be0 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
12bf0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
12c00 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
12c10 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
12c20 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
12c30 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
12c40 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
12c50 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
12c60 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
12c70 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
12c80 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
12c90 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
12ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12cb0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
12cc0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
12cd0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
12ce0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
12cf0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
12d00 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
12d10 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
12d20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
12d30 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
12d40 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
12d50 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
12d60 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
12d70 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
12d80 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
12d90 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
12da0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
12db0 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
12dc0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
12dd0 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
12de0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
12df0 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
12e00 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
12e10 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
12e20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
12e30 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
12e40 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
12e50 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
12e60 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
12e70 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
12e80 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
12e90 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
12ea0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
12eb0 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
12ec0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
12ed0 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
12ee0 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
12ef0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
12f00 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
12f10 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
12f20 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
12f30 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
12f40 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
12f50 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
12f60 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
12f70 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
12f80 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
12f90 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
12fa0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
12fb0 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
12fc0 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
12fd0 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
12fe0 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
12ff0 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
13000 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
13010 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
13020 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
13030 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
13040 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
13050 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
13060 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
13070 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
13080 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
13090 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
130a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
130b0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
130c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
130d0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
130e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
130f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
13100 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
13110 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
13120 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
13130 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
13140 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
13150 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
13160 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
13170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13180 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
13190 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
131a0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
131b0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
131c0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
131d0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
131e0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
131f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
13200 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
13210 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
13220 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
13230 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
13240 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
13250 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
13260 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
13270 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
13280 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
13290 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
132a0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
132b0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
132c0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
132d0 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
132e0 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
132f0 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
13300 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
13310 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
13320 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
13330 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
13340 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
13350 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
13360 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
13370 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
13380 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
13390 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
133a0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
133b0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
133c0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
133d0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
133e0 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
133f0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
13400 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
13410 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
13420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
13430 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
13440 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
13450 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
13460 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
13470 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
13480 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
13490 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
134a0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
134b0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
134c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
134d0 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
134e0 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
134f0 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
13500 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
13510 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
13520 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
13530 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
13540 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
13550 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
13560 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
13570 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
13580 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
13590 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
135a0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
135b0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
135c0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
135d0 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
135e0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
135f0 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
13600 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
13610 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
13620 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
13630 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
13640 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
13650 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
13660 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
13670 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
13680 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
13690 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
136a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
136b0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
136c0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
136d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
136e0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
136f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13700 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
13710 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
13720 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
13730 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
13740 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
13750 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
13760 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
13770 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
13780 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
13790 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
137a0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
137b0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
137c0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
137d0 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
137e0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
137f0 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
13800 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
13810 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
13820 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
13830 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
13840 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
13850 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
13860 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
13870 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
13880 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
13890 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
138a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
138b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
138c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
138d0 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
138e0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
138f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13900 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
13910 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
13920 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
13930 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
13940 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
13950 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
13960 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
13970 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
13980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13990 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
139a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
139b0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
139c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
139d0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
139e0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
139f0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
13a00 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
13a10 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
13a20 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
13a30 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
13a40 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
13a50 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
13a60 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
13a70 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
13a80 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
13a90 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
13aa0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
13ab0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
13ac0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
13ad0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
13ae0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
13af0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
13b00 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
13b10 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
13b20 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
13b30 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
13b40 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
13b50 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
13b60 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
13b70 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
13b80 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
13b90 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
13ba0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
13bb0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
13bc0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
13bd0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
13be0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
13bf0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
13c00 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
13c10 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
13c20 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
13c30 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
13c40 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
13c50 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
13c60 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
13c70 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
13c80 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
13c90 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
13ca0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
13cb0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
13cc0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
13cd0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
13ce0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
13cf0 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
13d00 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
13d10 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
13d20 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
13d30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
13d40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
13d50 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
13d60 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
13d70 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
13d80 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
13d90 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
13da0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
13db0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
13dc0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
13dd0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
13de0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
13df0 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
13e00 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
13e10 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
13e20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13e30 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
13e40 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
13e50 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
13e60 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
13e70 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
13e80 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
13e90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
13ea0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
13eb0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
13ec0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
13ed0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
13ee0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
13ef0 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
13f00 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
13f10 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
13f20 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
13f30 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
13f40 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
13f50 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
13f60 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13f70 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
13f80 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
13f90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
13fa0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
13fb0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
13fc0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
13fd0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
13fe0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
13ff0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
14000 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
14010 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
14020 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
14030 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
14040 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
14050 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
14060 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
14070 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
14080 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
14090 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
140a0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
140b0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
140c0 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
140d0 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
140e0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
140f0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
14100 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
14110 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
14120 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
14130 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
14140 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14150 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
14160 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
14170 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
14180 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
14190 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
141a0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
141b0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
141c0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
141d0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
141e0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
141f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
14200 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
14210 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
14220 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
14230 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
14240 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
14250 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
14260 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
14270 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
14280 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
14290 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
142a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
142b0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
142c0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
142d0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
142e0 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
142f0 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
14300 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
14310 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
14320 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
14330 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
14340 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
14350 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
14360 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
14370 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
14380 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
14390 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
143a0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
143b0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
143c0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
143d0 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
143e0 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
143f0 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
14400 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
14410 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
14420 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
14430 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
14440 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
14450 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
14460 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
14470 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
14480 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
14490 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
144a0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
144b0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
144c0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
144d0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
144e0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
144f0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
14500 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
14510 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
14520 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
14530 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
14540 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
14550 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
14560 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
14570 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
14580 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
14590 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
145a0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
145b0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
145c0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
145d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
145e0 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
145f0 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
14600 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
14610 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
14620 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
14630 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
14640 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
14650 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
14660 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
14670 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
14680 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
14690 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
146a0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
146b0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
146c0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
146d0 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
146e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
146f0 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
14700 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
14710 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
14720 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
14730 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
14740 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
14750 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
14760 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
14770 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
14780 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
14790 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
147a0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
147b0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
147c0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
147d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
147e0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
147f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
14800 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
14810 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
14820 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
14830 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
14840 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
14850 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
14860 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
14870 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
14880 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
14890 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
148a0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
148b0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
148c0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
148d0 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
148e0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
148f0 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
14900 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
14910 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
14920 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
14930 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
14940 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
14950 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
14960 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
14970 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
14980 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
14990 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
149a0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
149b0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
149c0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
149d0 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
149e0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
149f0 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
14a00 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
14a10 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
14a20 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
14a30 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
14a40 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
14a50 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
14a60 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
14a70 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
14a80 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
14a90 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
14aa0 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
14ab0 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
14ac0 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
14ad0 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
14ae0 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
14af0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
14b00 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
14b10 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
14b20 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
14b30 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
14b40 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
14b50 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
14b60 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
14b70 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
14b80 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
14b90 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
14ba0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14bb0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
14bc0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
14bd0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
14be0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
14bf0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
14c00 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
14c10 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
14c20 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
14c30 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
14c40 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
14c50 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
14c60 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
14c70 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
14c80 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
14c90 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
14ca0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14cb0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
14cc0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
14cd0 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
14ce0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
14cf0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
14d00 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
14d10 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
14d20 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
14d30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14d40 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
14d50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
14d60 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
14d70 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
14d80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
14d90 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
14da0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
14db0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
14dc0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
14dd0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
14de0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
14df0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
14e00 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
14e10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
14e20 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
14e30 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
14e40 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
14e50 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
14e60 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
14e70 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
14e80 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
14e90 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
14ea0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
14eb0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
14ec0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
14ed0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
14ee0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
14ef0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
14f00 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
14f10 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
14f20 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
14f30 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
14f40 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
14f50 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
14f60 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
14f70 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
14f80 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
14f90 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
14fa0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
14fb0 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
14fc0 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
14fd0 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
14fe0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
14ff0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
15000 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
15010 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
15020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15030 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
15040 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
15050 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
15060 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
15070 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
15080 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
15090 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
150a0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
150b0 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
150c0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
150d0 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20  eared.)^.*/.int 
150e0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
150f0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
15100 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
15110 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
15120 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
15130 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
15140 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
15150 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
15160 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
15170 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
15180 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15190 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
151a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
151b0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
151c0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
151d0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
151e0 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
151f0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
15200 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
15210 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
15220 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
15230 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
15240 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
15250 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
15260 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
15270 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
15280 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
15290 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
152a0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
152b0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
152c0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
152d0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
152e0 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
152f0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
15300 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
15310 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
15320 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
15330 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
15340 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
15350 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
15360 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
15370 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
15380 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
15390 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
153a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
153b0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
153c0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
153d0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
153e0 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
153f0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
15400 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
15410 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
15420 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
15430 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
15440 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
15450 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
15460 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
15470 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
15480 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
15490 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
154a0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
154b0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
154c0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
154d0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
154e0 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
154f0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
15500 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
15510 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
15520 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
15530 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
15540 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
15550 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15560 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
15570 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
15580 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
15590 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
155a0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
155b0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
155c0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
155d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
155e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
155f0 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
15600 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
15610 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
15620 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
15630 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
15640 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
15650 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15660 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
15670 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
15680 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
15690 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
156a0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
156b0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
156c0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
156d0 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
156e0 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
156f0 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
15700 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
15710 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
15720 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
15730 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
15740 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
15750 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
15760 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
15770 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
15780 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
15790 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
157a0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
157b0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
157c0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
157d0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
157e0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
157f0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
15800 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
15810 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15820 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
15830 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15840 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
15850 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
15860 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
15870 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
15880 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
15890 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
158a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
158b0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
158c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
158d0 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
158e0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
158f0 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
15900 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
15910 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
15920 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
15930 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
15940 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
15950 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
15960 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
15970 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15980 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
15990 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
159a0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
159b0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
159c0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
159d0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
159e0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
159f0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
15a00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
15a10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15a20 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
15a30 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
15a40 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
15a50 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
15a60 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
15a70 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
15a80 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
15a90 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
15aa0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
15ab0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
15ac0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
15ad0 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
15ae0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
15af0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
15b00 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
15b10 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
15b20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
15b30 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
15b40 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
15b50 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
15b60 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
15b70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
15b80 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
15b90 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
15ba0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
15bb0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
15bc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
15bd0 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
15be0 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
15bf0 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
15c00 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
15c10 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
15c20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
15c30 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
15c40 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
15c50 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
15c60 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
15c70 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
15c80 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
15c90 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
15ca0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
15cb0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
15cc0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
15cd0 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
15ce0 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
15cf0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
15d00 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
15d10 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
15d20 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
15d30 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
15d40 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
15d50 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
15d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
15d70 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
15d80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
15d90 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
15da0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
15db0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
15dc0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
15dd0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
15de0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
15df0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
15e00 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
15e10 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
15e20 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
15e30 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
15e40 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
15e50 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
15e60 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
15e70 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
15e80 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
15e90 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
15ea0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
15eb0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
15ec0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
15ed0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
15ee0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
15ef0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
15f00 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
15f10 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
15f20 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
15f30 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
15f40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
15f50 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
15f60 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
15f70 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
15f80 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
15f90 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
15fa0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
15fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
15fc0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
15fd0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
15fe0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
15ff0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
16000 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
16010 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
16020 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
16030 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
16040 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
16050 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
16060 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
16070 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
16080 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
16090 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
160a0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
160b0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
160c0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
160d0 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
160e0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
160f0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
16100 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
16110 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
16120 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
16130 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
16140 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
16150 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
16160 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
16170 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
16180 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
16190 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
161a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
161b0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
161c0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
161d0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
161e0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
161f0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
16200 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
16210 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
16220 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
16230 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
16240 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
16250 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
16260 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
16270 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
16280 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
16290 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
162a0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
162b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
162c0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
162d0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
162e0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
162f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16300 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
16310 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
16320 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
16330 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
16340 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
16350 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
16360 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
16370 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
16380 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
16390 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
163a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
163b0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
163c0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
163d0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
163e0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
163f0 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
16400 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
16410 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
16420 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
16430 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
16440 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
16450 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
16460 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
16470 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
16480 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
16490 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
164a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
164b0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
164c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
164d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
164e0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
164f0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
16500 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
16510 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
16520 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
16530 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16540 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
16550 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
16560 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
16570 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
16580 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
16590 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
165a0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
165b0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
165c0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
165d0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
165e0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
165f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
16600 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
16610 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
16620 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
16630 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
16640 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
16650 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
16660 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
16670 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
16680 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
16690 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
166a0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
166b0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
166c0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
166d0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
166e0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
166f0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
16700 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
16710 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
16720 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
16730 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
16740 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
16750 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
16760 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
16770 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
16780 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
16790 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
167a0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
167b0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
167c0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
167d0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
167e0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
167f0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
16800 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
16810 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
16820 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
16830 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
16840 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16850 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
16860 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
16870 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
16880 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
16890 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
168a0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
168b0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
168c0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
168d0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
168e0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
168f0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
16900 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
16910 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
16920 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
16930 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16940 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
16950 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
16960 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
16970 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
16980 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
16990 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
169a0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
169b0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
169c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
169d0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
169e0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
169f0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
16a00 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
16a10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
16a20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
16a30 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
16a40 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
16a50 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
16a60 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
16a70 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
16a80 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
16a90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16aa0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
16ab0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
16ac0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
16ad0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
16ae0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
16af0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
16b00 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
16b10 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
16b20 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
16b30 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
16b40 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
16b50 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
16b60 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
16b70 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
16b80 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
16b90 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
16ba0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
16bb0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
16bc0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
16bd0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
16be0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
16bf0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
16c00 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
16c10 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
16c20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
16c30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16c40 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
16c50 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
16c60 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
16c70 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
16c80 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
16c90 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
16ca0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16cb0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
16cc0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
16cd0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
16ce0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
16cf0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
16d00 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
16d10 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
16d20 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
16d30 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
16d40 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16d50 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
16d60 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
16d70 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
16d80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
16d90 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
16da0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
16db0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
16dc0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
16dd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
16de0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
16df0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
16e00 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
16e10 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
16e20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
16e30 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
16e40 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
16e50 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
16e60 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
16e70 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
16e80 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
16e90 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
16ea0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
16eb0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
16ec0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
16ed0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
16ee0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
16ef0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
16f00 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
16f10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
16f20 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
16f30 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
16f40 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
16f50 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
16f60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
16f70 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
16f80 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
16f90 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
16fa0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
16fb0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
16fc0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
16fd0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
16fe0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
16ff0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
17000 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
17010 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
17020 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
17030 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
17040 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
17050 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
17060 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
17070 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
17080 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
17090 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
170a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
170b0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
170c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
170d0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
170e0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
170f0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
17100 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
17110 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
17120 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
17130 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
17140 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
17150 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
17160 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
17170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17180 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
17190 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
171a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
171b0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
171c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
171d0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
171e0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
171f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
17200 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
17210 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
17220 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
17230 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
17240 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
17250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
17260 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
17270 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
17280 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
17290 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
172a0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
172b0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
172c0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
172d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
172e0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
172f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
17300 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
17310 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
17320 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
17330 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
17340 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
17350 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
17360 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
17370 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
17380 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
17390 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
173a0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
173b0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
173c0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
173d0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
173e0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
173f0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
17400 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
17410 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
17420 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
17430 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
17440 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
17450 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
17460 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
17470 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
17480 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
17490 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
174a0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
174b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
174c0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
174d0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
174e0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
174f0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
17500 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
17510 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
17520 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
17530 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
17540 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
17550 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
17560 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
17570 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
17580 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
17590 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
175a0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
175b0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
175c0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
175d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
175e0 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
175f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17600 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
17610 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
17620 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
17630 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17640 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
17650 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
17660 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
17670 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
17680 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
17690 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
176a0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
176b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
176c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
176d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
176e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
176f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
17700 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
17710 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
17720 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
17730 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
17740 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
17750 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
17760 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
17770 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
17780 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
17790 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
177a0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
177b0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
177c0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
177d0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
177e0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
177f0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
17800 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
17810 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
17820 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
17830 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
17840 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
17850 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
17860 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
17870 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
17880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
17890 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
178a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
178b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
178c0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
178d0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
178e0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
178f0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
17900 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
17910 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
17920 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
17930 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
17940 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
17950 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
17960 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
17970 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
17980 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
17990 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
179a0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
179b0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
179c0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
179d0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
179e0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
179f0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
17a00 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
17a10 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
17a20 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
17a30 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
17a40 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
17a50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
17a60 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
17a70 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
17a80 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
17a90 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
17aa0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
17ab0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
17ac0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
17ad0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
17ae0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
17af0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
17b00 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
17b10 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
17b20 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
17b30 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
17b40 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
17b50 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
17b60 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
17b70 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
17b80 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
17b90 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
17ba0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
17bb0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
17bc0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
17bd0 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
17be0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
17bf0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
17c00 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
17c10 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
17c20 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17c30 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
17c40 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
17c50 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
17c60 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
17c70 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
17c80 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
17c90 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
17ca0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
17cb0 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
17cc0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
17cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
17ce0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
17cf0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
17d00 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
17d10 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
17d20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
17d30 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
17d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
17d50 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
17d60 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
17d70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
17d80 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
17d90 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
17da0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
17db0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
17dc0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
17dd0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
17de0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
17df0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
17e00 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
17e10 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
17e20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
17e30 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
17e40 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
17e50 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
17e60 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
17e70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17e80 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
17e90 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
17ea0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
17eb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
17ec0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
17ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17ee0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
17ef0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17f00 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
17f10 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
17f20 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
17f30 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
17f40 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
17f50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
17f60 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
17f70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
17f80 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
17f90 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
17fa0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
17fb0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
17fc0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
17fd0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
17fe0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
17ff0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
18000 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
18010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
18020 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
18030 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
18040 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
18050 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
18060 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
18070 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
18080 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
18090 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
180a0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
180b0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
180c0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
180d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
180e0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
180f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
18100 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
18110 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
18120 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
18130 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
18140 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18150 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
18160 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
18170 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
18180 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
18190 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
181a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
181b0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
181c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
181d0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
181e0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
181f0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
18200 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
18210 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
18220 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
18230 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
18240 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18250 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
18260 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
18270 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
18280 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
18290 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
182a0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
182b0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
182c0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
182d0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
182e0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
182f0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
18300 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
18310 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
18320 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
18330 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
18340 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
18350 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
18360 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
18370 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
18380 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
18390 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
183a0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
183b0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
183c0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
183d0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
183e0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
183f0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
18400 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
18410 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
18420 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
18430 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
18440 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
18450 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
18460 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
18470 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
18480 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
18490 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
184a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
184b0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
184c0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
184d0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
184e0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
184f0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
18500 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
18510 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
18520 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
18530 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
18540 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
18550 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
18560 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
18570 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
18580 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
18590 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
185a0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
185b0 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
185c0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
185d0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
185e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
185f0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
18600 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
18610 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
18620 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
18630 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
18640 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
18650 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
18660 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18670 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
18680 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
18690 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
186a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
186b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
186c0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
186d0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
186e0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
186f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
18700 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
18710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18720 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
18730 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
18740 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
18750 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
18760 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
18770 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
18780 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
18790 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
187a0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
187b0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
187c0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
187d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
187e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
187f0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
18800 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
18810 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
18820 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18830 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
18840 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
18850 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
18860 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
18870 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
18880 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
18890 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
188a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
188b0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
188c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
188d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
188e0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
188f0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
18900 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
18910 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
18920 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
18930 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18940 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
18950 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
18960 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
18970 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
18980 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
18990 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
189a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
189b0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
189c0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
189d0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
189e0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
189f0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
18a00 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
18a10 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
18a20 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
18a30 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
18a40 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
18a50 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
18a60 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
18a70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18a80 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
18a90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
18aa0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
18ab0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
18ac0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
18ad0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
18ae0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
18af0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
18b00 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
18b10 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
18b20 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
18b30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
18b40 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
18b50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
18b60 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
18b70 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
18b80 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
18b90 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
18ba0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
18bb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18bc0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
18bd0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
18be0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
18bf0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
18c00 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
18c10 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
18c20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
18c30 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
18c40 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
18c50 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
18c60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
18c70 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
18c80 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
18c90 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
18ca0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
18cb0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
18cc0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
18cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
18ce0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
18cf0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
18d00 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
18d10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
18d20 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
18d30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
18d40 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
18d50 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
18d60 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
18d70 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
18d80 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
18d90 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
18da0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
18db0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
18dc0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
18dd0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
18de0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
18df0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
18e00 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
18e10 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
18e20 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
18e30 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
18e40 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
18e50 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
18e60 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
18e70 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
18e80 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18e90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
18ea0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
18eb0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
18ec0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
18ed0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
18ee0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
18ef0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
18f00 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
18f10 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
18f20 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
18f30 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
18f40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18f50 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
18f60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18f70 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
18f80 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
18f90 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
18fa0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
18fb0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
18fc0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
18fd0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
18fe0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
18ff0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
19000 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
19010 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
19020 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
19030 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
19040 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
19050 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
19060 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
19070 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
19080 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
19090 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
190a0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
190b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
190c0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
190d0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
190e0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
190f0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
19100 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
19110 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
19120 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
19130 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
19140 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
19150 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
19160 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
19170 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
19180 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
19190 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
191a0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
191b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
191c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
191d0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
191e0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
191f0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
19200 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
19210 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
19220 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
19230 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
19240 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
19250 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
19260 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
19270 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
19280 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
19290 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
192a0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
192b0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
192c0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
192d0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
192e0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
192f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
19300 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
19310 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
19320 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
19330 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
19340 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
19350 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
19360 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
19370 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
19380 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
19390 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
193a0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
193b0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
193c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
193d0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
193e0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
193f0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
19400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
19410 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19420 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19430 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
19440 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
19450 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
19460 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
19470 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
19480 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19490 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
194a0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
194b0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
194c0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
194d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
194e0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
194f0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
19500 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
19510 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
19520 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
19530 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
19540 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
19550 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
19560 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
19570 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
19580 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
19590 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
195a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
195b0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
195c0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
195d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
195e0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
195f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19600 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
19610 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
19620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
19630 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
19640 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
19650 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
19660 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
19670 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
19680 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
19690 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
196a0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
196b0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
196c0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
196d0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
196e0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
196f0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
19700 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
19710 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
19720 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
19730 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
19740 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
19750 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
19760 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
19770 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
19780 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
19790 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
197a0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
197b0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
197c0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
197d0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
197e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
197f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
19800 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
19810 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
19820 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
19830 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
19840 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
19850 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
19860 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
19870 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
19880 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
19890 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
198a0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
198b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
198c0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
198d0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
198e0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
198f0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
19900 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
19910 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
19920 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
19930 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
19940 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
19950 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
19960 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
19970 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
19980 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
19990 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
199a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
199b0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
199c0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
199d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
199e0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
199f0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
19a00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19a10 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
19a20 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
19a30 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
19a40 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
19a50 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
19a60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
19a70 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
19a80 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
19a90 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
19aa0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
19ab0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
19ac0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
19ad0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
19ae0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
19af0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19b00 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
19b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
19b20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
19b30 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
19b40 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
19b50 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
19b60 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
19b70 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
19b80 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
19b90 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
19ba0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19bb0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
19bc0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
19bd0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
19be0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
19bf0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
19c00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
19c10 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
19c20 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
19c30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19c40 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
19c50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
19c60 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
19c70 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
19c80 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
19c90 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
19ca0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
19cb0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
19cc0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
19cd0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
19ce0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
19cf0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
19d00 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
19d10 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
19d20 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
19d30 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
19d40 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
19d50 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
19d60 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
19d70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19d80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
19d90 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
19da0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
19db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19dc0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
19dd0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
19de0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19df0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19e10 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
19e20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
19e30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19e40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19e50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19e60 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
19e70 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
19e80 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
19e90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19eb0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
19ec0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
19ed0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19ee0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19f00 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
19f10 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
19f20 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
19f30 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19f50 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
19f60 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
19f70 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
19f80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19f90 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19fa0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
19fb0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
19fc0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19fd0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19fe0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19ff0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1a000 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1a010 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1a020 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a030 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1a040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1a050 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1a060 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1a070 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a080 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1a090 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1a0a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1a0b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1a0c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a0d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1a0e0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1a0f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1a100 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1a110 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a120 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1a130 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1a140 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1a150 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1a160 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a170 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1a180 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1a190 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a1a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a1b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a1c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1a1d0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1a1e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1a1f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a200 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a210 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1a220 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1a230 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1a240 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a250 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a260 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1a270 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1a280 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1a290 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a2a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a2b0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1a2c0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1a2d0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1a2e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a2f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a300 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1a310 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1a320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1a330 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1a340 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1a350 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1a360 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1a370 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1a380 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1a390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1a3a0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1a3b0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1a3c0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1a3d0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1a3e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1a3f0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1a400 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1a410 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1a420 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a430 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1a440 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1a450 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1a460 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1a470 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a480 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1a490 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1a4a0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1a4b0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1a4c0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1a4d0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1a4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1a4f0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1a500 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1a510 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a520 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1a530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1a540 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1a550 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1a560 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a570 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1a580 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1a590 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1a5a0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1a5b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a5c0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1a5d0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1a5e0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1a5f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1a600 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a610 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1a620 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1a630 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a640 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a650 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a660 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1a670 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1a680 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a690 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1a6a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a6b0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1a6c0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1a6d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a6e0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1a6f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a700 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1a710 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1a720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a730 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1a740 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a750 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1a760 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1a770 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1a780 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1a790 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a7a0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1a7b0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1a7c0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1a7d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a7e0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
1a7f0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
1a800 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1a810 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
1a820 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a830 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
1a840 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
1a850 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
1a860 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
1a870 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1a880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1a890 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1a8a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1a8b0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1a8c0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1a8d0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1a8e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1a8f0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1a900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a910 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
1a920 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1a930 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
1a940 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
1a950 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
1a960 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
1a970 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
1a980 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1a990 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1a9a0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
1a9b0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1a9c0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
1a9d0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
1a9e0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
1a9f0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
1aa00 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
1aa10 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
1aa20 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
1aa30 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
1aa40 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
1aa50 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
1aa60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1aa70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1aa80 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
1aa90 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
1aaa0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
1aab0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1aac0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
1aad0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
1aae0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
1aaf0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
1ab00 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
1ab10 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
1ab20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
1ab30 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
1ab40 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
1ab50 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1ab60 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
1ab70 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
1ab80 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
1ab90 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
1aba0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
1abb0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
1abc0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
1abd0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
1abe0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
1abf0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
1ac00 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
1ac10 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
1ac20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1ac30 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
1ac40 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
1ac50 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
1ac60 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
1ac70 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
1ac80 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1ac90 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
1aca0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1acb0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
1acc0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1acd0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
1ace0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
1acf0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1ad00 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1ad10 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1ad20 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1ad30 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1ad40 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1ad50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1ad60 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1ad70 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1ad80 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1ad90 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1ada0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1adb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1adc0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1add0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1ade0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
1adf0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
1ae00 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
1ae10 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
1ae20 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
1ae30 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
1ae40 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1ae50 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
1ae60 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
1ae70 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
1ae80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
1ae90 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
1aea0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
1aeb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aec0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
1aed0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1aee0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1aef0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1af00 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1af10 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1af20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1af30 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
1af40 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
1af50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1af60 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
1af70 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
1af80 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
1af90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  he number of .**
1afa0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
1afb0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
1afc0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
1afd0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
1afe0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
1aff0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
1b000 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  back X..**.** ^O
1b010 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
1b020 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
1b030 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
1b040 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
1b050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b060 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
1b070 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
1b080 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
1b090 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
1b0a0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
1b0b0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
1b0c0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
1b0d0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
1b0e0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1b0f0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
1b100 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
1b110 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
1b120 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
1b130 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
1b140 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1b150 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1b160 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1b170 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1b180 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1b190 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1b1a0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1b1b0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1b1c0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1b1d0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1b1e0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1b1f0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
1b200 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1b210 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1b220 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1b230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1b240 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1b250 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1b260 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1b270 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1b280 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1b290 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1b2a0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1b2b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b2c0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1b2d0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1b2e0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1b2f0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
1b300 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1b310 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1b320 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1b330 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1b340 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1b350 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1b360 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1b370 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b380 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1b390 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1b3a0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1b3b0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1b3c0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1b3d0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1b3e0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1b3f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1b400 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1b410 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1b420 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1b430 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1b440 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1b450 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1b460 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1b470 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1b480 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1b490 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1b4a0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1b4b0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1b4c0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1b4d0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1b4e0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1b4f0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1b500 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1b510 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1b520 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1b530 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1b540 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1b550 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1b560 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1b570 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1b580 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1b590 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1b5a0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1b5b0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1b5c0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1b5d0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1b5e0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1b5f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1b600 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1b610 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1b620 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1b630 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1b640 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1b650 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1b660 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1b670 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1b680 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1b690 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1b6a0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1b6b0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1b6c0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1b6d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1b6e0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1b6f0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b700 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1b710 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1b720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b730 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1b740 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1b750 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1b760 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1b770 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1b780 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1b790 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1b7a0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1b7b0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1b7c0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1b7d0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1b7e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1b7f0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1b800 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1b810 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1b820 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1b830 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1b840 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1b850 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b860 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1b870 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1b880 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1b890 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1b8a0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1b8b0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1b8c0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1b8d0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1b8e0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1b8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1b900 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1b910 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1b920 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1b930 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1b940 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1b950 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1b960 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1b970 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1b980 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b990 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1b9a0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1b9b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1b9c0 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  CACHE],.** and/o
1b9d0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
1b9e0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1b9f0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1ba00 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1ba10 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1ba20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ba30 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ba40 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1ba50 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1ba60 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1ba70 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1ba80 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1ba90 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1baa0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1bab0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1bac0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1bad0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1bae0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1baf0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1bb00 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1bb10 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1bb20 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1bb30 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1bb40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1bb50 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1bb60 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1bb70 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1bb80 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1bb90 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1bba0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1bbb0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1bbc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1bbd0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1bbe0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1bbf0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1bc00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1bc10 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1bc20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1bc30 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1bc40 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1bc50 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1bc60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1bc70 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1bc80 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1bc90 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1bca0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1bcb0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1bcc0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1bcd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1bce0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1bcf0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1bd00 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1bd10 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1bd20 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1bd30 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1bd40 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1bd50 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1bd60 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1bd70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1bd80 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1bd90 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1bda0 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1bdb0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1bdc0 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1bdd0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1bde0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1bdf0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1be00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1be10 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1be20 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1be30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1be40 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1be50 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1be60 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1be70 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1be80 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1be90 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1bea0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1beb0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1bec0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1bed0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1bee0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1bef0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1bf00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1bf10 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1bf20 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1bf30 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1bf40 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1bf50 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1bf60 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1bf70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1bf80 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1bf90 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1bfa0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1bfb0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1bfc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1bfd0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1bfe0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1bff0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1c000 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1c010 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1c020 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1c030 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1c040 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1c050 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1c060 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1c070 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1c080 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
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 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1c0b0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1c0c0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1c0d0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1c0e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1c0f0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1c100 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1c110 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1c120 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1c130 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1c140 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1c150 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1c160 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1c170 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1c180 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1c190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c1a0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1c1b0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1c1c0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1c1d0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1c1e0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1c1f0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1c200 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1c210 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1c220 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1c230 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1c240 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1c250 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1c260 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1c270 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1c280 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1c290 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1c2a0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1c2b0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1c2c0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1c2d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1c2e0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1c2f0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1c300 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1c310 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1c320 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1c330 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1c340 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1c350 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1c360 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1c370 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1c380 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c390 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1c3a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1c3b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1c3c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c3d0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1c3e0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1c3f0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1c400 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1c410 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1c420 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1c430 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1c440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1c450 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1c460 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1c470 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1c480 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1c490 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1c4a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1c4b0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1c4c0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1c4d0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1c4e0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1c4f0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1c500 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1c510 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1c520 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1c530 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1c540 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1c550 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1c560 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1c570 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1c580 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1c590 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1c5a0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1c5b0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1c5c0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1c5d0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1c5e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1c5f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1c600 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c610 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1c620 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1c630 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1c640 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1c650 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1c660 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1c670 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1c680 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1c690 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1c6a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1c6b0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1c6c0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1c6d0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1c6e0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1c6f0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1c700 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1c710 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1c720 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1c730 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1c740 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1c750 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1c760 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1c770 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1c780 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1c790 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1c7a0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1c7b0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1c7c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1c7d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1c7e0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1c7f0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1c800 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1c810 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1c820 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1c830 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1c840 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1c850 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1c860 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1c870 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1c880 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1c890 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1c8a0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1c8b0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1c8c0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1c8d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c8e0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1c8f0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1c900 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1c910 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1c920 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1c930 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1c940 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1c950 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1c960 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1c970 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1c980 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1c990 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1c9a0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1c9b0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1c9c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1c9d0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1c9e0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1c9f0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1ca00 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1ca10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1ca20 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1ca30 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1ca40 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1ca50 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1ca60 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1ca70 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1ca80 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1ca90 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1caa0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1cab0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1cac0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1cad0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1cae0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1caf0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1cb00 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1cb10 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1cb20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1cb30 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1cb40 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1cb50 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1cb60 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1cb70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1cb80 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1cb90 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1cba0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1cbb0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1cbc0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1cbd0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1cbe0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1cbf0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1cc00 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1cc10 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1cc20 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1cc30 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1cc40 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1cc50 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1cc60 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1cc70 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1cc80 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1cc90 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1cca0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1ccb0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1ccc0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1ccd0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1cce0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1ccf0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1cd00 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1cd10 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1cd20 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1cd30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1cd40 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1cd50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1cd60 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1cd70 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1cd80 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1cd90 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1cda0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1cdb0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1cdc0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1cdd0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1cde0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1cdf0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1ce00 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1ce10 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1ce20 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1ce30 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1ce40 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1ce50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1ce60 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1ce70 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1ce80 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1ce90 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1cea0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1ceb0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1cec0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1ced0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1cee0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1cef0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1cf00 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1cf10 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1cf20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1cf30 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1cf40 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1cf50 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1cf60 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1cf70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1cf80 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1cf90 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1cfa0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1cfb0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1cfc0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1cfd0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1cfe0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1cff0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1d000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1d010 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1d020 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1d030 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1d040 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1d050 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1d060 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1d070 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1d080 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1d090 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1d0a0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1d0b0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1d0c0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1d0d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1d0e0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1d0f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1d100 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1d110 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1d120 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1d130 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1d140 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1d150 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1d160 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1d170 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1d180 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1d190 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1d1a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d1b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1d1c0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1d1d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1d1e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1d1f0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1d200 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1d210 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1d220 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1d230 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1d240 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1d250 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1d260 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1d270 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1d280 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1d290 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1d2a0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1d2b0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1d2c0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1d2d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1d2e0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1d2f0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1d300 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1d310 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1d320 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1d330 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1d340 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1d350 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1d360 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1d370 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1d380 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1d390 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1d3a0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1d3b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d3c0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1d3d0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1d3e0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1d3f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d400 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1d410 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1d420 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1d430 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1d440 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1d450 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1d460 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1d470 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1d480 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1d490 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
1d4a0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1d4b0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1d4c0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1d4d0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1d4e0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
1d4f0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
1d500 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
1d510 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
1d520 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1d530 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1d540 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
1d550 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
1d560 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1d570 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
1d580 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1d590 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
1d5a0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1d5b0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1d5c0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1d5d0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
1d5e0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
1d5f0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
1d600 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1d610 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
1d620 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
1d630 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
1d640 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
1d650 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1d660 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
1d670 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
1d680 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1d690 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
1d6a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1d6b0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
1d6c0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
1d6d0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
1d6e0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1d6f0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
1d700 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
1d710 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
1d720 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
1d730 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
1d740 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
1d750 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
1d760 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
1d770 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
1d780 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1d790 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
1d7a0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
1d7b0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
1d7c0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
1d7d0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
1d7e0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
1d7f0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
1d800 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
1d810 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
1d820 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
1d830 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
1d840 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1d850 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1d860 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1d870 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1d880 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1d890 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1d8a0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1d8b0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1d8c0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1d8d0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1d8e0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1d8f0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1d900 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1d910 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1d920 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1d930 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1d940 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1d950 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1d960 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1d970 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1d980 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
1d990 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1d9a0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1d9b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1d9c0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1d9d0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1d9e0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1d9f0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1da00 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1da10 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1da20 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1da30 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1da40 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1da50 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1da60 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1da70 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
1da80 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
1da90 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
1daa0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1dab0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
1dac0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1dad0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1dae0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1daf0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1db00 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1db10 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
1db20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1db30 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
1db40 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
1db50 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
1db60 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
1db70 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
1db80 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
1db90 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
1dba0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1dbb0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1dbc0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
1dbd0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1dbe0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
1dbf0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
1dc00 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
1dc10 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
1dc20 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
1dc30 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
1dc40 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
1dc50 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1dc60 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
1dc70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1dc80 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
1dc90 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
1dca0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
1dcb0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
1dcc0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1dcd0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1dce0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1dcf0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1dd00 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1dd10 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
1dd20 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1dd30 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1dd40 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1dd50 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1dd60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1dd70 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1dd80 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1dd90 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1dda0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
1ddb0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1ddc0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1ddd0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1dde0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1ddf0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1de00 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
1de10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1de20 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1de30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1de40 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1de50 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1de60 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1de70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1de80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1de90 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1dea0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1deb0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1dec0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1ded0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1dee0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1def0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1df00 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1df10 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1df20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1df30 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1df40 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1df50 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1df60 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1df70 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1df80 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
1df90 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
1dfa0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
1dfb0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
1dfc0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
1dfd0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
1dfe0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
1dff0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e000 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1e010 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1e020 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e030 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1e040 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1e050 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
1e060 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e070 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1e080 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e090 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e0a0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1e0b0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1e0c0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28  )^</dd>.**.** ^(
1e0d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e0e0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1e0f0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1e100 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1e110 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1e120 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1e130 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
1e140 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
1e150 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e160 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e170 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1e180 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1e190 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
1e1a0 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
1e1b0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
1e1c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
1e1d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1e1e0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1e1f0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1e200 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e210 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
1e220 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
1e230 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1e240 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e250 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1e260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e270 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1e280 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1e290 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1e2a0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1e2b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1e2c0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1e2d0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1e2e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1e2f0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1e300 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1e310 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1e320 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1e330 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1e340 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1e350 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1e360 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1e370 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1e380 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1e390 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1e3a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e3b0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1e3c0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1e3d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e3e0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1e3f0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1e400 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e410 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1e420 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1e430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e440 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1e450 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1e460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e470 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1e480 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
1e490 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1e4a0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1e4b0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1e4c0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1e4d0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1e4e0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1e4f0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1e500 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1e510 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1e520 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1e530 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1e540 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1e550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1e560 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1e570 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
1e580 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1e590 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1e5a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1e5b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
1e5c0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
1e5d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e5e0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
1e5f0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
1e600 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1e610 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1e620 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1e630 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1e640 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1e650 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1e660 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1e670 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1e680 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1e690 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1e6a0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1e6b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1e6c0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1e6d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e6e0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1e6f0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
1e700 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1e710 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1e720 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1e730 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1e740 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1e750 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
1e760 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1e770 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1e780 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1e790 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1e7a0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1e7b0 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
1e7c0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1e7d0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1e7e0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1e7f0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1e800 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1e810 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1e820 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1e830 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1e840 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1e850 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1e860 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1e870 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1e880 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1e890 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1e8a0 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1e8b0 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1e8c0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1e8d0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1e8e0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1e8f0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1e900 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1e910 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1e920 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1e930 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1e940 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
1e950 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
1e960 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
1e970 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1e980 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1e990 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
1e9a0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1e9b0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1e9c0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1e9d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1e9e0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
1e9f0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
1ea00 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1ea10 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1ea20 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
1ea30 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
1ea40 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
1ea50 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1ea60 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1ea70 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1ea80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1ea90 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1eaa0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1eab0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
1eac0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1ead0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1eae0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
1eaf0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1eb00 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1eb10 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1eb20 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1eb30 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1eb40 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1eb50 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1eb60 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
1eb70 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1eb80 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1eb90 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1eba0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1ebb0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1ebc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1ebd0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1ebe0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
1ebf0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
1ec00 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
1ec10 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
1ec20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1ec30 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
1ec40 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1ec50 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
1ec60 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1ec70 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1ec80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ec90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1eca0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1ecb0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1ecc0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1ecd0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1ece0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1ecf0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1ed00 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1ed10 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1ed20 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1ed30 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1ed40 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1ed50 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
1ed60 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1ed70 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1ed80 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1ed90 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1eda0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1edb0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1edc0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1edd0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1ede0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1edf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1ee00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1ee10 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
1ee20 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
1ee30 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1ee40 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1ee50 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1ee60 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1ee70 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1ee80 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1ee90 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1eea0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1eeb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1eec0 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1eed0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1eee0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1eef0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1ef00 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
1ef10 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1ef20 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1ef30 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1ef40 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1ef50 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1ef60 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1ef70 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1ef80 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1ef90 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1efa0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1efb0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1efc0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1efd0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1efe0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1eff0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1f000 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1f010 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1f020 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1f030 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1f040 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1f050 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1f060 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1f070 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1f080 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1f090 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1f0a0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1f0b0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1f0c0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1f0d0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1f0e0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1f0f0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1f100 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
1f110 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
1f120 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1f130 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1f140 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
1f150 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
1f160 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
1f170 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
1f180 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
1f190 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1f1a0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
1f1b0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1f1c0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
1f1d0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
1f1e0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
1f1f0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
1f200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1f210 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1f220 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
1f230 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1f240 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
1f250 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
1f260 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
1f270 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
1f280 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
1f290 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
1f2a0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
1f2b0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
1f2c0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
1f2d0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
1f2e0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
1f2f0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
1f300 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
1f310 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
1f320 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
1f330 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
1f340 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
1f350 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
1f360 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT2] compile-ti
1f370 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
1f380 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
1f390 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
1f3a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1f3b0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1f3c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1f3d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1f3e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f3f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1f400 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1f410 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1f420 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1f430 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1f440 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1f450 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1f460 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1f470 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1f480 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1f490 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1f4a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1f4b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1f4c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1f4d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1f4e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1f4f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1f500 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1f510 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f520 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1f530 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1f540 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1f550 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1f560 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1f570 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1f580 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1f590 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1f5a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1f5b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1f5c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1f5d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1f5e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1f5f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1f600 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1f610 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1f620 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1f630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f640 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1f650 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f660 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f670 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f680 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f6a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1f6b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f6c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f6d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1f6e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1f6f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1f700 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1f710 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1f720 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f730 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1f740 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1f750 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1f760 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1f770 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1f780 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1f790 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1f7a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1f7b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1f7c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1f7d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1f7e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1f7f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1f800 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1f810 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1f820 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1f830 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1f840 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1f850 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1f860 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1f870 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1f880 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1f890 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1f8a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1f8b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1f8c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1f8d0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1f8e0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
1f8f0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f900 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1f910 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1f920 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1f930 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1f940 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1f950 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f960 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1f970 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1f980 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1f990 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f9a0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1f9b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1f9c0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
1f9d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1f9e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1f9f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1fa00 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1fa10 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1fa20 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
1fa30 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
1fa40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
1fa50 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
1fa60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1fa70 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
1fa80 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
1fa90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1faa0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
1fab0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
1fac0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
1fad0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
1fae0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
1faf0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
1fb00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1fb10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
1fb20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
1fb30 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
1fb40 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
1fb50 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
1fb60 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
1fb70 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
1fb80 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
1fb90 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
1fba0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
1fbb0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
1fbc0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1fbd0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
1fbe0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1fbf0 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
1fc00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
1fc10 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
1fc20 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
1fc30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1fc40 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
1fc50 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
1fc60 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
1fc70 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1fc80 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
1fc90 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
1fca0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
1fcb0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
1fcc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1fcd0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
1fce0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
1fcf0 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
1fd00 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
1fd10 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
1fd20 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
1fd30 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
1fd40 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
1fd50 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
1fd60 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
1fd70 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
1fd80 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
1fd90 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
1fda0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
1fdb0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
1fdc0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
1fdd0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
1fde0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
1fdf0 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
1fe00 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
1fe10 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
1fe20 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
1fe30 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
1fe40 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
1fe50 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
1fe60 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
1fe70 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
1fe80 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
1fe90 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
1fea0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
1feb0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
1fec0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
1fed0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
1fee0 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
1fef0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
1ff00 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
1ff10 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
1ff20 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
1ff30 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
1ff40 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
1ff50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
1ff60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1ff70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1ff80 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
1ff90 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
1ffa0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1ffb0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1ffc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1ffd0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1ffe0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1fff0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
20000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20010 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
20020 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
20030 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
20040 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
20050 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
20060 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
20070 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
20080 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
20090 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
200a0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
200b0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
200c0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
200d0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
200e0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
200f0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
20100 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
20110 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
20120 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
20130 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
20140 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
20150 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
20160 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
20170 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
20180 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
20190 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
201a0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
201b0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
201c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
201d0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
201e0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
201f0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
20200 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
20210 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
20220 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
20230 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
20240 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
20250 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
20260 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
20270 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
20280 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
20290 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
202a0 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
202b0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
202c0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
202d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
202e0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
202f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
20300 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
20310 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
20320 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
20330 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
20340 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
20350 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
20360 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
20370 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
20380 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
20390 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
203a0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
203b0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
203c0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
203d0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
203e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
203f0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
20400 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
20410 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
20420 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
20430 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
20440 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
20450 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
20460 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20470 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
20480 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
20490 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
204a0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
204b0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
204c0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
204d0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
204e0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
204f0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
20500 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
20510 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
20520 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20530 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
20540 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
20550 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
20560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20570 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20580 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
20590 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
205a0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
205b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
205c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
205d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
205e0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
205f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20600 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
20610 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
20620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
20630 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
20640 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
20650 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20660 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
20670 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
20680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
20690 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
206a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
206b0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
206c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
206d0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
206e0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
206f0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
20700 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
20710 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20720 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
20730 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
20740 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
20750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20760 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
20770 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
20780 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
20790 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
207a0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
207b0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
207c0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
207d0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
207e0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
207f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
20800 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
20810 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
20820 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
20830 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
20840 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
20850 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
20860 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
20870 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
20880 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
20890 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
208a0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
208b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
208c0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
208d0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
208e0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
208f0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
20900 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
20910 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20920 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
20930 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
20940 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
20950 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
20960 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
20970 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
20980 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
20990 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
209a0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
209b0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
209c0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
209d0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
209e0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
209f0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
20a00 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
20a10 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
20a20 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
20a30 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
20a40 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
20a50 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
20a60 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
20a70 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20a80 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
20a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20aa0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
20ab0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
20ac0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
20ad0 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
20ae0 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
20af0 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
20b00 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
20b10 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
20b20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
20b30 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
20b40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
20b50 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
20b60 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
20b70 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
20b80 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
20b90 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
20ba0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
20bb0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
20bc0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
20bd0 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
20be0 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
20bf0 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
20c00 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
20c10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
20c20 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
20c30 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
20c40 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
20c50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20c60 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
20c70 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
20c80 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
20c90 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
20ca0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
20cb0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
20cc0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
20cd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
20ce0 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
20cf0 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
20d00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20d10 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20d20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
20d30 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
20d40 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
20d50 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
20d60 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
20d70 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
20d80 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
20d90 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
20da0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
20db0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
20dc0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
20dd0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
20de0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
20df0 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
20e00 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
20e10 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
20e20 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
20e30 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
20e40 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
20e50 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
20e60 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
20e70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20e80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
20e90 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
20ea0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
20eb0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
20ec0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
20ed0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
20ee0 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
20ef0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
20f00 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
20f10 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
20f20 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
20f30 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20f40 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
20f50 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
20f60 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
20f70 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
20f80 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
20f90 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
20fa0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
20fb0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
20fc0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
20fd0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
20fe0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
20ff0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
21000 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
21010 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
21020 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
21030 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
21040 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
21050 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
21060 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
21070 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
21080 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
21090 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
210a0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
210b0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
210c0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
210d0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
210e0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
210f0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
21100 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21110 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
21120 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21130 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
21140 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
21150 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
21160 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
21170 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
21180 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
21190 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
211a0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
211b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
211c0 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
211d0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
211e0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
211f0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
21200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21210 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
21220 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
21230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21240 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
21250 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
21260 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
21270 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
21280 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
21290 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
212a0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
212b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
212c0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
212d0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
212e0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
212f0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
21300 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
21310 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
21320 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
21330 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
21340 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
21350 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
21360 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
21370 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
21380 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
21390 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
213a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
213b0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
213c0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
213d0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
213e0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
213f0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
21400 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
21410 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
21420 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
21430 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
21440 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
21450 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
21460 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
21470 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
21480 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
21490 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
214a0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
214b0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
214c0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
214d0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
214e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
214f0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
21500 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
21510 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
21520 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
21530 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
21540 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
21550 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
21560 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
21570 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
21580 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
21590 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
215a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
215b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
215c0 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
215d0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
215e0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
215f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
21600 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
21610 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
21620 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
21630 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
21640 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
21650 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
21660 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
21670 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
21680 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
21690 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
216a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
216b0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
216c0 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
216d0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
216e0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
216f0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
21700 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
21710 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
21720 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21730 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
21740 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
21750 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
21760 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
21770 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
21780 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
21790 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
217a0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
217b0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
217c0 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
217d0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
217e0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
217f0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
21800 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
21810 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
21820 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
21830 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
21840 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
21850 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21860 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21870 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
21880 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
21890 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
218a0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
218b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
218c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
218d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
218e0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
218f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21900 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
21910 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
21920 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21930 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
21940 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
21950 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
21960 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
21970 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
21980 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
21990 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
219a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
219b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
219c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
219d0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
219e0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
219f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21a10 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
21a20 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
21a30 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
21a40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
21a50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21a60 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
21a70 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
21a80 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
21a90 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
21aa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21ab0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
21ac0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
21ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
21ae0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
21af0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
21b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21b10 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
21b20 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
21b30 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
21b40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
21b50 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
21b60 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
21b70 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
21b80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
21b90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
21ba0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
21bb0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
21bc0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
21bd0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
21be0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
21bf0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
21c00 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
21c10 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21c20 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
21c30 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
21c40 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
21c50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
21c60 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
21c70 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
21c80 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
21c90 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
21ca0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
21cb0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
21cc0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
21cd0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
21ce0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
21cf0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
21d00 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
21d10 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
21d20 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
21d30 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
21d40 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
21d50 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
21d60 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21d70 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21d80 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21d90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21da0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
21db0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21dc0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21dd0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
21de0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21df0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
21e00 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
21e10 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
21e20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
21e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21e40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21e50 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
21e60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
21e70 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
21e80 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
21e90 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
21ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21eb0 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
21ec0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
21ed0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
21ee0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
21ef0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
21f00 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
21f10 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
21f20 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
21f30 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
21f40 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
21f50 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
21f60 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
21f70 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
21f80 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
21f90 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
21fa0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
21fb0 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
21fc0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
21fd0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
21fe0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
21ff0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
22000 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
22010 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
22020 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
22030 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
22040 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
22050 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
22060 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
22070 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
22080 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
22090 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
220a0 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
220b0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
220c0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
220d0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
220e0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
220f0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
22100 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
22110 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
22120 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
22130 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
22140 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
22150 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
22160 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
22170 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22180 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
22190 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
221a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
221b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
221c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
221d0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
221e0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
221f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22200 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
22210 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22220 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22230 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
22240 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
22250 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
22260 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
22270 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
22280 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
22290 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
222a0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
222b0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
222c0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
222d0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
222e0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
222f0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
22300 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
22310 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22320 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
22330 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
22340 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
22350 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
22360 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
22370 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
22380 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
22390 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
223a0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
223b0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
223c0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
223d0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
223e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
223f0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
22400 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
22410 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22420 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
22430 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
22440 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
22450 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
22460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22470 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
22480 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
22490 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
224a0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
224b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
224c0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
224d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
224e0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
224f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
22500 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
22510 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
22520 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
22530 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
22540 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
22550 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
22560 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
22570 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
22580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
22590 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
225a0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
225b0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
225c0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
225d0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
225e0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
225f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
22600 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
22610 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
22620 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
22630 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
22640 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22650 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
22660 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
22670 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
22680 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
22690 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
226a0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
226b0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
226c0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
226d0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
226e0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
226f0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
22700 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
22710 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
22720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
22730 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
22740 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22760 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
22770 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
22780 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
22790 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
227a0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
227b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
227c0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
227d0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
227e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
227f0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
22800 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
22810 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22820 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
22830 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
22840 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
22850 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
22860 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
22870 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
22880 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
22890 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
228a0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
228b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
228c0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
228d0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
228e0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
228f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
22900 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
22910 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
22920 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
22930 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
22940 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
22950 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
22960 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
22970 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
22980 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
22990 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
229a0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
229b0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
229c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
229d0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
229e0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
229f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22a00 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
22a10 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
22a20 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
22a30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
22a40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
22a50 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
22a60 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
22a70 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
22a80 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
22a90 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
22aa0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
22ab0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
22ac0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
22ad0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
22ae0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
22af0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
22b00 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
22b10 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
22b20 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
22b30 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
22b40 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
22b50 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
22b60 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
22b70 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
22b80 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
22b90 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
22ba0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
22bb0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
22bc0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
22bd0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22be0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
22bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22c00 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
22c10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22c20 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
22c30 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
22c40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22c50 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
22c60 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
22c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
22c80 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
22c90 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
22ca0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
22cb0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
22cc0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
22cd0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
22ce0 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
22cf0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
22d00 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
22d10 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
22d20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
22d30 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
22d40 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
22d50 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
22d60 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
22d70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
22d80 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
22d90 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
22da0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
22db0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
22dc0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
22dd0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
22de0 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
22df0 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
22e00 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
22e10 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
22e20 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
22e30 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
22e40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22e50 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
22e60 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
22e70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22e80 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
22e90 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
22ea0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
22eb0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
22ec0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
22ed0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
22ee0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
22ef0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
22f00 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
22f10 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
22f20 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
22f30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
22f40 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
22f50 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
22f60 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
22f70 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
22f80 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
22f90 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
22fa0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
22fb0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
22fc0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
22fd0 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
22fe0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
22ff0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
23000 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
23010 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
23020 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
23030 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
23040 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
23050 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
23060 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
23070 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
23080 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
23090 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
230a0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
230b0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
230c0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
230d0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
230e0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
230f0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
23100 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
23110 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
23120 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
23130 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
23140 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
23150 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
23160 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
23170 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
23180 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
23190 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
231a0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
231b0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
231c0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
231d0 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
231e0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
231f0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
23200 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
23210 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
23220 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
23230 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
23240 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
23250 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
23260 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
23270 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
23280 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
23290 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
232a0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
232b0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
232c0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
232d0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
232e0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
232f0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
23300 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
23310 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
23320 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
23330 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
23340 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
23350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
23360 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
23370 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
23380 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
23390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
233a0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
233b0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
233c0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
233d0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
233e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
233f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
23400 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
23410 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
23420 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
23430 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
23440 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23450 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
23460 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23470 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
23490 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
234a0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
234b0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
234c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
234d0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
234e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
234f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23500 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
23510 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
23520 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
23530 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
23540 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
23550 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23560 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
23580 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
23590 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
235a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
235b0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
235c0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
235d0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
235e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
235f0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
23600 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
23610 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
23620 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
23630 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
23640 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
23650 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
23660 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
23670 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
23680 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
23690 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
236a0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
236b0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
236c0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
236d0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
236e0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
236f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23700 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
23710 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
23720 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
23730 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
23740 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
23750 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
23760 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
23770 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
23780 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
23790 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
237a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
237b0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
237c0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
237d0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
237e0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
237f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
23800 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
23810 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
23820 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
23830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
23840 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
23850 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
23860 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
23870 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
23880 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
23890 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
238a0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
238b0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
238c0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
238d0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
238e0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
238f0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
23900 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
23910 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
23920 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
23930 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
23940 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
23950 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
23960 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
23970 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
23980 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
23990 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
239a0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
239b0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
239c0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
239d0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
239e0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
239f0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
23a00 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
23a10 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
23a20 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
23a30 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23a40 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
23a50 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
23a60 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
23a70 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23a80 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
23a90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23ab0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
23ac0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
23ad0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
23ae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
23af0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
23b00 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
23b10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23b20 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
23b30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23b40 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
23b50 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
23b60 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
23b70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
23b80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23b90 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
23ba0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
23bb0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
23bc0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
23bd0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
23be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
23bf0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
23c00 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
23c10 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
23c20 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
23c30 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
23c40 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
23c50 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
23c60 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
23c70 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
23c80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23c90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23ca0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
23cb0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
23cc0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
23cd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
23ce0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
23cf0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
23d00 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
23d10 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
23d20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
23d30 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
23d40 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
23d50 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
23d60 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
23d70 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
23d80 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
23d90 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
23da0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
23db0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
23dc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
23dd0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
23de0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
23df0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
23e00 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
23e10 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
23e20 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
23e30 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
23e40 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
23e50 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
23e60 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
23e70 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
23e80 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
23e90 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
23ea0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
23eb0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
23ec0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
23ed0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
23ee0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
23ef0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
23f00 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
23f10 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
23f20 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
23f30 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
23f40 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
23f50 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
23f60 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
23f70 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
23f80 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
23f90 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
23fa0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
23fb0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
23fc0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
23fd0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
23fe0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
23ff0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
24000 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
24010 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
24020 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
24030 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
24040 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
24050 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
24060 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
24070 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
24080 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
24090 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
240a0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
240b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
240c0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
240d0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
240e0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
240f0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
24100 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
24110 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
24120 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
24130 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
24140 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
24150 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
24160 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
24170 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
24180 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
24190 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
241a0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
241b0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
241c0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
241d0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
241e0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
241f0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
24200 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
24210 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
24220 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
24230 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
24240 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
24250 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
24260 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
24270 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
24280 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
24290 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
242a0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
242b0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
242c0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
242d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
242e0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
242f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
24300 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
24310 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
24320 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
24330 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
24340 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
24350 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
24360 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
24370 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
24380 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
24390 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
243a0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
243b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
243c0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
243d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
243e0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
243f0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
24400 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
24410 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
24420 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
24430 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
24440 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
24450 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
24460 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
24470 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
24480 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
24490 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
244a0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
244b0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
244c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
244d0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
244e0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
244f0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
24500 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
24510 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
24520 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
24530 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
24540 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
24550 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
24560 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
24570 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
24580 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
24590 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
245a0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
245b0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
245c0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
245d0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
245e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
245f0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
24600 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
24610 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
24620 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
24630 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
24640 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
24650 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
24660 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
24670 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
24680 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
24690 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
246a0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
246b0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
246c0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
246d0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
246e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
246f0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
24700 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
24710 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
24720 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
24730 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
24740 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
24750 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
24760 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
24770 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
24780 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
24790 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
247a0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
247b0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
247c0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
247d0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
247e0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
247f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
24800 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
24810 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
24820 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
24830 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
24840 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
24850 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
24860 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
24870 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
24880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
24890 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
248a0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
248b0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
248c0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
248d0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
248e0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
248f0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
24900 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
24910 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
24920 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
24930 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
24940 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
24950 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
24960 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
24970 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
24980 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
24990 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
249a0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
249b0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
249c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
249d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
249e0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
249f0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
24a00 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
24a10 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
24a20 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
24a30 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
24a40 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
24a50 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
24a60 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
24a70 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
24a80 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
24a90 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
24aa0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
24ab0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
24ac0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
24ad0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
24ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24af0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
24b00 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
24b10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24b20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24b30 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
24b40 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
24b50 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
24b60 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
24b70 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
24b80 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
24b90 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
24ba0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
24bb0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
24bc0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
24bd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
24be0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
24bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24c00 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
24c10 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
24c20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
24c30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
24c40 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
24c50 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
24c60 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
24c70 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
24c80 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
24c90 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
24ca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
24cb0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
24cc0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
24cd0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
24ce0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
24cf0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
24d00 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
24d10 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
24d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
24d30 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
24d40 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
24d50 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
24d60 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
24d70 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
24d80 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
24d90 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
24da0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
24db0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nter..**.** See 
24dc0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
24dd0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
24de0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
24df0 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
24e00 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24e10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
24e30 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
24e40 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
24e50 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
24e60 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
24e70 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
24e80 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
24e90 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
24ea0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
24eb0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
24ec0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
24ed0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24ee0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
24ef0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
24f00 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
24f10 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
24f20 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
24f30 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
24f40 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
24f50 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
24f60 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
24f70 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
24f80 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
24f90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
24fa0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
24fb0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
24fc0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
24fd0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
24fe0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
24ff0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
25000 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
25010 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
25020 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
25030 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
25040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25050 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
25060 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
25070 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
25080 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
25090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
250a0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
250b0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
250c0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
250d0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
250e0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
250f0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
25100 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
25110 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
25120 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
25130 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
25140 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
25150 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
25160 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
25170 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
25180 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
25190 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
251a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
251b0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
251c0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
251d0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
251e0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
251f0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
25200 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
25210 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
25220 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
25230 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
25240 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25250 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
25260 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
25270 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
25280 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
25290 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
252a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
252b0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
252c0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
252d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
252e0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
252f0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
25300 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
25310 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
25320 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
25330 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
25340 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
25350 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
25360 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
25370 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25380 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
25390 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
253a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
253b0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
253c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
253d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
253e0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
253f0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
25400 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
25410 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
25420 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
25430 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
25440 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
25450 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
25460 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
25470 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
25480 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
25490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
254a0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
254b0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
254c0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
254d0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
254e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
254f0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
25500 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
25510 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
25520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
25530 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
25540 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25550 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
25560 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
25570 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
25580 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
25590 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
255a0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
255b0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
255c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
255d0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
255e0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
255f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25600 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
25610 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
25620 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
25630 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
25640 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
25650 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
25660 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
25670 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
25680 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
25690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
256a0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
256b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
256c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
256d0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
256e0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
256f0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
25700 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
25710 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
25720 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
25730 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
25740 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
25750 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
25760 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
25770 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
25780 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
25790 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
257a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
257b0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
257c0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
257d0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
257e0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
257f0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
25800 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
25810 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
25820 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
25830 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
25840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
25850 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
25860 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
25870 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
25880 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
25890 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
258a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
258b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
258c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
258d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
258e0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
258f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
25900 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
25910 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
25920 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25940 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
25950 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
25960 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
25970 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
25980 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
25990 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
259a0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
259b0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
259c0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
259d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
259e0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
259f0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
25a00 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
25a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25a20 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
25a30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
25a40 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
25a50 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
25a60 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
25a70 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
25a80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
25a90 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
25aa0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25ab0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
25ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25ad0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
25ae0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
25af0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
25b00 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
25b10 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
25b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25b30 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
25b40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
25b50 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
25b60 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
25b70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
25b80 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
25b90 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
25ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25bb0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
25bc0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
25bd0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
25be0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
25bf0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
25c00 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25c10 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
25c20 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
25c30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
25c40 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
25c50 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
25c60 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
25c70 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
25c80 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
25c90 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
25ca0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
25cb0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
25cc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
25cd0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
25ce0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
25cf0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
25d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
25d10 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
25d20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25d30 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
25d40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25d50 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
25d60 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
25d70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
25d80 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
25d90 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
25da0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
25db0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
25dc0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
25dd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
25de0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
25df0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
25e00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
25e10 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
25e20 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
25e30 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
25e40 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
25e50 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
25e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25e70 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
25e80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
25e90 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
25ea0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
25eb0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
25ec0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
25ed0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
25ee0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25ef0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
25f00 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
25f10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
25f20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
25f30 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
25f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
25f50 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
25f60 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
25f70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
25f80 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
25f90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25fa0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
25fb0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
25fc0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
25fd0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
25fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
25ff0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
26000 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
26010 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26020 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
26030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
26040 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
26050 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
26060 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
26070 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
26080 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
26090 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
260a0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
260b0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
260c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
260d0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
260e0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
260f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
26100 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
26110 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
26120 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
26130 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
26140 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
26150 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
26160 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
26170 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
26180 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
26190 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
261a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
261b0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
261c0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
261d0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
261e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
261f0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
26200 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
26210 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
26220 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
26230 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
26240 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
26250 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
26260 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
26270 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
26280 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
26290 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
262a0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
262b0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
262c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
262d0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
262e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
262f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
26300 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
26310 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
26320 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
26330 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
26340 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
26350 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
26360 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
26370 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
26380 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
26390 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
263a0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
263b0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
263c0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
263d0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
263e0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
263f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
26400 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
26410 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
26420 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
26430 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
26440 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
26450 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
26460 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
26470 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
26480 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
26490 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
264a0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
264b0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
264c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
264d0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
264e0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
264f0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
26500 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
26510 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
26520 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
26530 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
26540 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
26550 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
26560 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
26570 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
26580 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
26590 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
265a0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
265b0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
265c0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
265d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
265e0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
265f0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
26600 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
26610 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
26620 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
26630 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
26640 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
26650 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
26660 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
26670 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
26680 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
26690 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
266a0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
266b0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
266c0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
266d0 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
266e0 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
266f0 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
26700 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
26710 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
26720 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
26730 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
26740 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
26750 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
26760 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
26770 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
26780 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
26790 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
267a0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
267b0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
267c0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
267d0 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
267e0 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
267f0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
26800 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
26810 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
26820 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
26830 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
26840 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
26850 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
26860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
26870 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
26880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26890 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
268a0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
268b0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
268c0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
268d0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
268e0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
268f0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
26900 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
26910 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
26920 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
26930 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
26940 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
26950 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
26960 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
26970 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
26980 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
26990 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
269a0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
269b0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
269c0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
269d0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
269e0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
269f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26a00 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
26a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26a20 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
26a30 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
26a40 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26a50 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
26a60 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
26a70 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
26a80 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
26a90 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
26aa0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
26ab0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
26ac0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
26ad0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
26ae0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
26af0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
26b00 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
26b10 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
26b20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
26b30 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
26b40 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
26b50 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
26b60 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
26b70 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
26b80 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
26b90 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
26ba0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
26bb0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
26bc0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
26bd0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
26be0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
26bf0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
26c00 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
26c10 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
26c20 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
26c30 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
26c40 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
26c50 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
26c60 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
26c70 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
26c80 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
26c90 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
26ca0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
26cb0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
26cc0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
26cd0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
26ce0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
26cf0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
26d00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
26d10 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
26d20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
26d30 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
26d40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
26d50 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
26d60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
26d70 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
26d80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26d90 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
26da0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
26db0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
26dc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
26dd0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
26de0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
26df0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
26e00 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
26e10 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
26e20 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
26e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
26e40 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
26e50 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
26e60 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
26e70 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
26e80 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
26e90 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
26ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26eb0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
26ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26ed0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
26ee0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
26ef0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
26f00 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
26f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26f20 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
26f30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
26f40 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
26f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26f60 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
26f70 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
26f80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26f90 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
26fa0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
26fb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
26fc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
26fd0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
26fe0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
26ff0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
27000 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
27010 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
27020 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
27030 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
27040 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
27050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
27060 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
27070 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
27080 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
27090 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
270a0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
270b0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
270c0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
270d0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
270e0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
270f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
27100 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
27110 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
27120 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
27130 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
27140 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
27150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
27160 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
27170 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
27180 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
27190 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
271a0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
271b0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
271c0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
271d0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
271e0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
271f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
27200 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
27210 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
27220 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
27230 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
27240 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
27250 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
27260 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
27270 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27280 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
27290 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
272a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
272b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
272c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
272d0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
272e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
272f0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
27300 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
27310 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
27320 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
27330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
27340 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
27350 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
27360 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
27370 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
27380 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
27390 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
273a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
273b0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
273c0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
273d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
273e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
273f0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
27400 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27410 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
27420 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27430 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
27440 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
27450 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27460 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
27470 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
27480 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
27490 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
274a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
274b0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
274c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
274d0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
274e0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
274f0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
27500 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
27510 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
27520 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
27530 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27540 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
27550 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
27560 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
27570 72 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74  rs or.** or if t
27580 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
27590 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
275a0 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
275b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
275c0 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
275d0 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
275e0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
275f0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
27600 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
27610 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
27620 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
27630 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
27640 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
27650 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
27660 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
27670 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
27680 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
27690 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
276a0 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
276b0 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
276c0 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
276d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
276e0 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
276f0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
27700 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
27710 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
27720 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
27730 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
27740 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
27750 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27760 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
27770 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
27780 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
27790 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
277a0 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
277b0 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
277c0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
277d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
277e0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
277f0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
27800 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
27810 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
27820 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27830 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
27840 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
27850 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
27860 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
27870 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
27880 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
27890 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
278a0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
278b0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
278c0 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
278d0 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
278e0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
278f0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
27900 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
27910 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
27920 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
27930 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
27940 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
27950 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
27960 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27970 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
27980 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
279a0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
279b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
279c0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
279d0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
279e0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
279f0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
27a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27a10 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
27a20 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
27a30 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
27a40 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
27a50 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
27a60 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
27a70 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
27a80 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
27a90 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
27aa0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
27ab0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
27ac0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
27ad0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
27ae0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
27af0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
27b00 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
27b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
27b20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
27b30 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
27b40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27b50 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
27b60 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
27b70 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
27b80 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
27b90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
27ba0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
27bb0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
27bc0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
27bd0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
27be0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
27bf0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
27c00 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
27c10 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
27c20 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
27c30 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
27c40 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
27c50 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
27c60 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
27c70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
27c80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
27c90 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
27ca0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
27cb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27cc0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
27cd0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
27ce0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
27cf0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
27d00 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
27d10 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
27d20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
27d30 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
27d40 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
27d50 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
27d60 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
27d70 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
27d80 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
27d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27da0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
27db0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
27dc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27dd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
27de0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
27df0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
27e00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
27e10 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
27e20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
27e30 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
27e40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
27e50 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
27e60 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
27e70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
27e80 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
27e90 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
27ea0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
27eb0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
27ec0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
27ed0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
27ee0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
27ef0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
27f00 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
27f10 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
27f20 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
27f30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
27f40 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
27f50 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
27f60 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
27f70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
27f80 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
27f90 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
27fa0 0a 2a 2a 20 74 68 65 20 74 68 65 20 73 65 63 6f  .** the the seco
27fb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
27fc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
27fd0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
27fe0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
27ff0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
28000 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
28010 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
28020 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
28030 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
28040 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
28050 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
28060 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
28070 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
28080 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
28090 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
280a0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
280b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
280c0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
280d0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
280e0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
280f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28100 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
28110 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
28120 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
28130 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
28140 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
28150 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28160 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
28170 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
28180 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
28190 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
281a0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
281b0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
281c0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
281d0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
281e0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
281f0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
28200 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
28210 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
28220 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
28230 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
28240 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
28250 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
28260 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
28270 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
28280 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
28290 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
282a0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
282b0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
282c0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
282d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
282e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
282f0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
28300 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
28310 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
28320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
28330 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
28340 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
28350 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
28360 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
28370 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
28380 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
28390 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
283a0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
283b0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
283c0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
283d0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
283e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
283f0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
28400 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
28410 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
28420 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
28430 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
28440 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
28450 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
28460 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28470 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
28480 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
28490 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
284a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
284b0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
284c0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
284d0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
284e0 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
284f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
28500 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
28510 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
28520 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
28530 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
28540 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
28550 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
28560 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
28570 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
28580 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
28590 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
285a0 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
285b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
285c0 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
285d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
285e0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
285f0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
28600 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
28610 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
28620 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
28630 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
28640 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
28650 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
28660 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
28670 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
28680 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
28690 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
286a0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
286b0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
286c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
286d0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
286e0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
286f0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
28700 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
28710 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
28720 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
28730 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
28740 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
28750 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
28760 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
28770 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
28780 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
28790 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
287a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
287b0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
287c0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
287d0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
287e0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
287f0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
28800 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
28810 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
28820 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
28830 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
28840 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
28850 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
28860 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
28870 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
28880 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
28890 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
288a0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
288b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
288c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
288d0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
288e0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
288f0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
28900 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
28910 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
28920 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
28930 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
28940 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
28950 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
28960 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
28970 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
28980 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
28990 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
289a0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
289b0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
289c0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
289d0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
289e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 65 72 73 20 66  s NULL poiners f
289f0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
28a00 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
28a10 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
28a20 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
28a30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
28a40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
28a50 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
28a60 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
28a70 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
28a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
28a90 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
28aa0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
28ab0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
28ac0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
28ad0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
28ae0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
28af0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
28b00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
28b10 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
28b20 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
28b30 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
28b40 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
28b50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
28b60 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
28b70 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
28b80 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
28b90 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
28ba0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
28bb0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
28bc0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
28bd0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
28be0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
28bf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28c00 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
28c10 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
28c20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
28c30 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
28c40 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
28c50 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
28c60 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
28c70 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
28c80 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
28c90 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
28ca0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
28cb0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
28cc0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
28cd0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
28ce0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
28cf0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
28d00 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
28d10 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
28d20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
28d30 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
28d40 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
28d50 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
28d60 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
28d70 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
28d80 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
28d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
28da0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
28db0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
28dc0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
28dd0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
28de0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
28df0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
28e00 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
28e10 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
28e20 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
28e30 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
28e40 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
28e50 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
28e60 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
28e70 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
28e80 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
28e90 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
28ea0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
28eb0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
28ec0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
28ed0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
28ee0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
28ef0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
28f00 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
28f10 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
28f20 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
28f30 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
28f40 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
28f50 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
28f60 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
28f70 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
28f80 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
28f90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28fa0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
28fb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28fc0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
28fd0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
28fe0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
28ff0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
29000 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
29010 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
29020 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
29030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
29040 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
29050 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
29060 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
29070 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
29080 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
29090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
290a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
290b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
290c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
290d0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
290e0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
290f0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
29100 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
29110 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
29120 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
29130 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
29140 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
29150 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
29160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
29170 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
29180 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
29190 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
291a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
291b0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
291c0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
291d0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
291e0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
291f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
29200 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
29210 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
29220 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
29230 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
29240 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
29250 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
29260 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
29270 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
29280 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
29290 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
292a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
292b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
292c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
292d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
292e0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
292f0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
29300 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
29310 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
29320 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
29330 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
29340 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
29350 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
29360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
29370 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
29380 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
29390 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
293a0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
293b0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
293c0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
293d0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
293e0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
293f0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
29400 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
29410 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
29420 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
29430 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
29440 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
29450 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29460 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
29470 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
29480 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
29490 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
294a0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
294b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
294c0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
294d0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
294e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
294f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
29500 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
29510 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
29520 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29530 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
29540 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
29550 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
29560 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29570 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
29580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29590 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
295a0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
295b0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
295c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
295d0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
295e0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
295f0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
29600 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
29610 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
29620 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
29630 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
29640 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
29650 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
29660 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
29670 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
29680 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
29690 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
296a0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
296b0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
296c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
296d0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
296e0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
296f0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
29700 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
29710 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
29720 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
29730 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
29740 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
29750 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
29760 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29770 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
29780 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
29790 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
297a0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
297b0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
297c0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
297d0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
297e0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
297f0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
29800 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
29810 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
29820 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
29830 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
29840 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
29850 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
29860 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
29870 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
29880 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
29890 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
298a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
298b0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
298c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
298d0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
298e0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
298f0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
29900 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
29910 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
29920 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
29930 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
29940 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
29950 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
29960 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
29970 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
29980 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
29990 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
299a0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
299b0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
299c0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
299d0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
299e0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
299f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29a00 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
29a10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29a20 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
29a30 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
29a40 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
29a50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
29a60 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
29a70 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
29a80 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
29a90 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
29aa0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
29ab0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
29ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29ad0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
29ae0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
29af0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
29b00 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
29b10 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
29b20 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
29b30 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
29b40 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
29b50 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
29b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29b70 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
29b80 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
29b90 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
29ba0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29bb0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
29bc0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
29bd0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
29be0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
29bf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29c00 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
29c10 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
29c20 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
29c30 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
29c40 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
29c50 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
29c60 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
29c70 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
29c80 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
29c90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
29ca0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
29cb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29cc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
29cd0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
29ce0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
29cf0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
29d00 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
29d10 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
29d20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
29d30 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
29d40 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
29d50 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
29d60 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
29d70 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
29d80 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
29d90 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
29da0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
29db0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
29dc0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
29dd0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
29de0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
29df0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
29e00 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
29e10 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
29e20 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
29e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
29e40 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
29e50 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
29e60 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
29e70 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
29e80 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
29e90 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
29ea0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
29eb0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
29ec0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
29ed0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
29ee0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
29ef0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
29f00 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
29f10 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
29f20 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
29f30 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
29f40 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
29f50 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
29f60 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
29f70 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
29f80 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
29f90 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
29fa0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
29fb0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
29fc0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
29fd0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
29fe0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
29ff0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
2a000 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
2a010 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
2a020 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
2a030 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
2a040 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
2a050 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2a060 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2a070 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
2a080 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2a090 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
2a0a0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
2a0b0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
2a0c0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2a0d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2a0e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2a0f0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
2a100 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a110 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2a120 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2a130 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
2a140 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2a150 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2a160 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
2a170 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2a180 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
2a190 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
2a1a0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
2a1b0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
2a1c0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2a1d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2a1e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2a1f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
2a200 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a210 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2a220 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2a230 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
2a240 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2a250 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
2a260 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2a270 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
2a280 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
2a290 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2a2a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2a2b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a2c0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2a2d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
2a2e0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
2a2f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2a300 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2a310 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2a320 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2a330 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a340 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2a350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2a360 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a370 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a380 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
2a390 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2a3a0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
2a3b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2a3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2a3d0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2a3e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2a3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2a400 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2a410 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
2a420 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
2a430 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
2a440 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
2a450 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
2a460 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
2a470 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
2a480 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
2a490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a4a0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
2a4b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2a4c0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2a4d0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
2a4e0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2a4f0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2a500 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
2a510 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
2a520 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
2a530 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
2a540 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2a550 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
2a560 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
2a570 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2a580 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
2a590 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2a5a0 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
2a5b0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2a5c0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2a5d0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
2a5e0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
2a5f0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
2a600 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2a610 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
2a620 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
2a630 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
2a640 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
2a650 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
2a660 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
2a670 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
2a680 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
2a690 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
2a6a0 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
2a6b0 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
2a6c0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
2a6d0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
2a6e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2a6f0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
2a700 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
2a710 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
2a720 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
2a730 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
2a740 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
2a750 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2a760 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
2a770 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
2a780 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
2a790 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
2a7a0 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
2a7b0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2a7c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2a7d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2a7e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a7f0 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
2a800 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
2a810 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
2a820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
2a830 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
2a840 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
2a850 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
2a860 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
2a870 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2a880 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
2a890 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
2a8a0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
2a8b0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2a8c0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
2a8d0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
2a8e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2a8f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
2a900 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2a910 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
2a920 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2a930 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
2a940 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
2a950 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
2a960 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
2a970 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
2a980 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
2a990 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2a9a0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
2a9b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2a9c0 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
2a9d0 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
2a9e0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
2a9f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2aa00 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
2aa10 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
2aa20 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2aa30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2aa40 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2aa50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2aa60 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
2aa70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2aa80 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2aa90 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2aaa0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
2aab0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2aac0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2aad0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2aae0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2aaf0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
2ab00 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2ab10 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2ab20 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ab30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ab40 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2ab50 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
2ab60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ab70 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
2ab80 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
2ab90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
2aba0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
2abb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2abc0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2abd0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
2abe0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
2abf0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
2ac00 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2ac10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2ac20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2ac30 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2ac40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ac50 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2ac60 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2ac70 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2ac80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2ac90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2aca0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2acb0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
2acc0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2acd0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2ace0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2acf0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ad00 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2ad10 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2ad20 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
2ad30 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2ad40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2ad50 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2ad60 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
2ad70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ad80 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2ad90 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
2ada0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2adb0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2adc0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
2add0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
2ade0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
2adf0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
2ae00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ae10 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
2ae20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ae30 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
2ae40 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
2ae50 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
2ae60 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
2ae70 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2ae80 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
2ae90 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
2aea0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
2aeb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2aec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2aed0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
2aee0 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
2aef0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
2af00 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
2af10 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
2af20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
2af30 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
2af40 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
2af50 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
2af60 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
2af70 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
2af80 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
2af90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2afa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
2afb0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
2afc0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
2afd0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
2afe0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
2aff0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
2b000 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
2b010 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
2b020 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
2b030 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
2b040 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
2b050 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
2b060 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
2b070 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
2b080 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
2b090 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
2b0a0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
2b0b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2b0c0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
2b0d0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
2b0e0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
2b0f0 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
2b100 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
2b110 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
2b120 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
2b130 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
2b140 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2b150 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
2b160 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
2b170 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
2b180 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2b190 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
2b1a0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
2b1b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
2b1c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2b1d0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2b1e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b1f0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
2b200 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
2b210 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
2b220 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
2b230 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
2b240 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
2b250 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
2b260 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b270 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
2b280 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
2b290 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
2b2a0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
2b2b0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
2b2c0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
2b2d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
2b2e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
2b2f0 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
2b300 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
2b310 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
2b320 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
2b330 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
2b340 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2b350 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2b360 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2b370 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2b380 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
2b390 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
2b3a0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
2b3b0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
2b3c0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
2b3d0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
2b3e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2b3f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2b400 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
2b410 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2b420 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2b430 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
2b440 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
2b450 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
2b460 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
2b470 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
2b480 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
2b490 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2b4a0 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
2b4b0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
2b4c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2b4d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2b4e0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
2b4f0 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
2b500 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
2b510 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2b520 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
2b530 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
2b540 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
2b550 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
2b560 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
2b570 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
2b580 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
2b590 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
2b5a0 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
2b5b0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
2b5c0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
2b5d0 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
2b5e0 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
2b5f0 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
2b600 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
2b610 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
2b620 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
2b630 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
2b640 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
2b650 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
2b660 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
2b670 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
2b680 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
2b690 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
2b6a0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
2b6b0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
2b6c0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
2b6d0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
2b6e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2b6f0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2b700 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2b710 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2b720 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
2b730 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2b740 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2b750 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2b760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b770 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
2b780 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2b790 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2b7a0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
2b7b0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
2b7c0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
2b7d0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
2b7e0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
2b7f0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
2b800 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
2b810 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
2b820 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
2b830 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
2b840 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2b850 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
2b860 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
2b870 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
2b880 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
2b890 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2b8a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2b8b0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2b8c0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
2b8d0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
2b8e0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
2b8f0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
2b900 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2b910 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2b920 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
2b930 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
2b940 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
2b950 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2b960 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
2b970 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
2b980 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
2b990 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
2b9a0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
2b9b0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
2b9c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
2b9d0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
2b9e0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
2b9f0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
2ba00 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
2ba10 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
2ba20 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
2ba30 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
2ba40 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
2ba50 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
2ba60 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2ba70 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
2ba80 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
2ba90 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
2baa0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
2bab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bac0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
2bad0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2bae0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
2baf0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
2bb00 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
2bb10 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
2bb20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2bb30 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
2bb40 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
2bb50 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
2bb60 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
2bb70 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
2bb80 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
2bb90 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
2bba0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2bbb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2bbc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2bbd0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
2bbe0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2bbf0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
2bc00 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
2bc10 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
2bc20 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
2bc30 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
2bc40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
2bc50 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
2bc60 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
2bc70 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
2bc80 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
2bc90 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
2bca0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
2bcb0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2bcc0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2bcd0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2bce0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bcf0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
2bd00 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2bd10 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2bd20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2bd30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2bd40 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
2bd50 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
2bd60 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
2bd70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2bd80 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
2bd90 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
2bda0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
2bdb0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2bdc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bdd0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2bde0 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
2bdf0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2be00 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2be10 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2be20 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
2be30 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
2be40 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
2be50 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
2be60 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2be70 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
2be80 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2be90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bea0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
2beb0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2bec0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2bed0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2bee0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2bef0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
2bf00 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
2bf10 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
2bf20 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
2bf30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bf40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2bf50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2bf60 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2bf70 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
2bf80 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
2bf90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2bfa0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
2bfb0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
2bfc0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
2bfd0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
2bfe0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
2bff0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
2c000 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2c010 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2c020 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
2c030 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
2c040 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
2c050 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
2c060 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
2c070 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
2c080 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2c090 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
2c0a0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
2c0b0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
2c0c0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2c0d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2c0e0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
2c0f0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
2c100 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
2c110 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2c120 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2c130 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2c140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c150 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
2c160 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2c170 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
2c180 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
2c190 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
2c1a0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2c1b0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2c1c0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2c1d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c1e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2c1f0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2c200 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2c210 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2c220 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2c230 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
2c240 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2c250 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
2c260 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
2c270 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2c280 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
2c290 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c2a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2c2b0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2c2c0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2c2d0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
2c2e0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2c2f0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2c300 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2c310 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2c320 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2c330 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2c340 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2c350 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2c360 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2c370 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
2c380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2c390 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2c3a0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2c3b0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2c3c0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2c3d0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2c3e0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2c3f0 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
2c400 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
2c410 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
2c420 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
2c430 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
2c440 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c450 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2c460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c470 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
2c480 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
2c490 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
2c4a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2c4b0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
2c4c0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2c4d0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2c4e0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2c4f0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
2c500 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
2c510 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
2c520 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2c530 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
2c540 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
2c550 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2c560 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2c570 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2c580 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
2c590 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
2c5a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c5b0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
2c5c0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2c5d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2c5e0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2c5f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c600 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2c610 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
2c620 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2c630 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2c640 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2c650 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c660 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
2c670 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2c680 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2c690 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c6a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c6b0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
2c6c0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2c6d0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2c6e0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2c6f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2c700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2c710 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2c720 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2c730 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2c740 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c750 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2c760 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
2c770 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c780 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
2c790 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2c7a0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
2c7b0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2c7c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2c7d0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2c7e0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2c7f0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2c800 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2c810 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c820 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2c830 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2c840 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2c850 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2c860 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2c870 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2c880 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2c890 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2c8a0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2c8b0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
2c8c0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
2c8d0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
2c8e0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
2c8f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2c900 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
2c910 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2c920 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
2c930 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2c940 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2c950 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2c960 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2c970 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2c980 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
2c990 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
2c9a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
2c9b0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2c9c0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2c9d0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2c9e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2c9f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2ca00 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2ca10 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
2ca20 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
2ca30 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
2ca40 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
2ca50 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
2ca60 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
2ca70 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2ca80 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
2ca90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2caa0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
2cab0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2cac0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2cad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2cae0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2caf0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2cb00 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2cb10 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
2cb20 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2cb30 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
2cb40 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
2cb50 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
2cb60 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2cb70 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
2cb80 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
2cb90 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2cba0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2cbb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2cbc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cbd0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2cbe0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
2cbf0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2cc00 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2cc10 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
2cc20 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
2cc30 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
2cc40 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2cc50 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
2cc60 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
2cc70 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
2cc80 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
2cc90 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2cca0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
2ccb0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
2ccc0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
2ccd0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
2cce0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2ccf0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2cd00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2cd10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cd20 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2cd30 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2cd40 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2cd50 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2cd60 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
2cd70 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
2cd80 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2cd90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
2cda0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
2cdb0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
2cdc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2cdd0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
2cde0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2cdf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2ce00 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2ce10 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2ce20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2ce30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ce40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
2ce50 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
2ce60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ce70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
2ce80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
2ce90 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
2cea0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2ceb0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2cec0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2ced0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2cee0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2cef0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
2cf00 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
2cf10 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
2cf20 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
2cf30 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
2cf40 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
2cf50 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2cf60 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
2cf70 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
2cf80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cf90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2cfa0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
2cfb0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
2cfc0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2cfd0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cfe0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
2cff0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
2d000 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2d010 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
2d020 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
2d030 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2d040 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
2d050 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
2d060 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
2d070 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
2d080 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
2d090 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2d0a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d0b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
2d0c0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
2d0d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2d0e0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
2d0f0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2d100 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
2d110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2d120 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
2d130 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2d140 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2d150 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2d160 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2d170 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2d180 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
2d190 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d1a0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
2d1b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d1c0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
2d1d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d1e0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
2d1f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d200 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
2d210 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d220 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
2d230 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2d240 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d250 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
2d260 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
2d270 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2d280 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2d290 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
2d2a0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
2d2b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d2c0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
2d2d0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
2d2e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d2f0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
2d300 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
2d310 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
2d320 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
2d330 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d340 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2d350 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
2d360 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2d370 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
2d380 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d390 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d3a0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
2d3b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2d3c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2d3d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d3e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d3f0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
2d400 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d410 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d420 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2d430 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d440 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2d450 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d460 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2d470 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2d480 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2d490 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
2d4a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d4b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d4c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d4d0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
2d4e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d4f0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
2d500 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
2d510 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
2d520 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
2d530 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2d540 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
2d550 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
2d560 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
2d570 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2d580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d590 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
2d5a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d5b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2d5c0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
2d5d0 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
2d5e0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
2d5f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d600 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
2d610 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2d620 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
2d630 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2d640 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
2d650 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
2d660 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2d670 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
2d680 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
2d690 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
2d6a0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
2d6b0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
2d6c0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
2d6d0 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
2d6e0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
2d6f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2d700 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
2d710 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
2d720 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
2d730 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
2d740 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
2d750 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
2d760 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
2d770 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
2d780 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2d790 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
2d7a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2d7b0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
2d7c0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
2d7d0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
2d7e0 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
2d7f0 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
2d800 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
2d810 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2d820 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
2d830 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
2d840 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
2d850 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
2d860 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
2d870 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
2d880 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
2d890 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
2d8a0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
2d8b0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
2d8c0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2d8d0 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
2d8e0 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
2d8f0 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
2d900 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
2d910 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
2d920 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
2d930 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
2d940 61 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  a application da
2d950 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
2d960 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
2d970 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
2d980 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2d990 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2d9a0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
2d9b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2d9c0 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
2d9d0 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
2d9e0 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
2d9f0 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
2da00 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
2da10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
2da20 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
2da30 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
2da40 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
2da50 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
2da60 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
2da70 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
2da80 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
2da90 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2daa0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2dab0 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
2dac0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
2dad0 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
2dae0 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
2daf0 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
2db00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
2db10 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
2db20 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
2db30 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
2db40 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
2db50 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
2db60 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
2db70 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
2db80 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
2db90 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2dba0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2dbb0 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
2dbc0 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
2dbd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2dbe0 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
2dbf0 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
2dc00 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
2dc10 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
2dc20 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
2dc30 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
2dc40 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
2dc50 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
2dc60 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
2dc70 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
2dc80 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
2dc90 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
2dca0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
2dcb0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
2dcc0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
2dcd0 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
2dce0 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
2dcf0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
2dd00 73 74 20 61 6c 77 61 79 20 72 65 74 75 72 6e 20  st alway return 
2dd10 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
2dd20 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
2dd30 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
2dd40 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
2dd50 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
2dd60 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
2dd70 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
2dd80 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
2dd90 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
2dda0 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
2ddb0 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
2ddc0 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
2ddd0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
2dde0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
2ddf0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
2de00 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
2de10 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
2de20 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
2de30 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
2de40 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
2de50 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
2de60 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
2de70 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
2de80 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
2de90 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
2dea0 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
2deb0 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
2dec0 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
2ded0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
2dee0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
2def0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
2df00 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
2df10 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
2df20 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
2df30 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
2df40 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
2df50 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
2df60 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
2df70 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2df80 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
2df90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2dfa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dfb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2dfc0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
2dfd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2dfe0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
2dff0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
2e000 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
2e010 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
2e020 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
2e030 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
2e040 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
2e050 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
2e060 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e070 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
2e080 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
2e090 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
2e0a0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
2e0b0 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
2e0c0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
2e0d0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
2e0e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e0f0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
2e100 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
2e110 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
2e120 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
2e130 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
2e140 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
2e150 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2e160 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2e170 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
2e180 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
2e190 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
2e1a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e1b0 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
2e1c0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
2e1d0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
2e1e0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
2e1f0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
2e200 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
2e210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2e220 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
2e230 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
2e240 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
2e250 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
2e260 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
2e270 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
2e280 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
2e290 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
2e2a0 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
2e2b0 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
2e2c0 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
2e2d0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
2e2e0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
2e2f0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
2e300 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
2e310 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e320 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
2e330 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
2e340 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
2e350 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2e360 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2e370 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e380 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
2e390 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e3a0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2e3b0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
2e3c0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
2e3d0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2e3e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2e3f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2e400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2e410 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e420 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2e430 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2e440 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2e450 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
2e460 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
2e470 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2e480 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2e490 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
2e4a0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2e4b0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2e4c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e4d0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
2e4e0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
2e4f0 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
2e500 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2e510 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
2e520 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2e530 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2e540 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2e550 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2e560 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
2e570 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
2e580 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
2e590 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
2e5a0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
2e5b0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
2e5c0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
2e5d0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
2e5e0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
2e5f0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
2e600 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
2e610 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2e620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2e630 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2e640 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
2e650 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2e660 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
2e670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2e680 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
2e690 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
2e6a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
2e6b0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
2e6c0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
2e6d0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
2e6e0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
2e6f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2e700 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
2e710 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2e720 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
2e730 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2e740 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
2e750 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
2e760 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
2e770 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
2e780 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
2e790 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
2e7a0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
2e7b0 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
2e7c0 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
2e7d0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
2e7e0 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
2e7f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2e800 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
2e810 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
2e820 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
2e830 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2e840 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
2e850 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
2e860 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
2e870 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2e880 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
2e890 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
2e8a0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2e8b0 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
2e8c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2e8d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
2e8e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2e8f0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
2e900 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
2e910 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
2e920 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
2e930 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
2e940 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
2e950 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
2e960 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2e970 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2e980 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
2e990 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
2e9a0 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
2e9b0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
2e9c0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
2e9d0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
2e9e0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
2e9f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2ea00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2ea10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2ea20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2ea30 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2ea40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ea50 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
2ea60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2ea70 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
2ea80 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
2ea90 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
2eaa0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2eab0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
2eac0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
2ead0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2eae0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
2eaf0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
2eb00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2eb10 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2eb20 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
2eb30 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
2eb40 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
2eb50 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2eb60 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
2eb70 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
2eb80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
2eb90 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
2eba0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
2ebb0 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
2ebc0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2ebd0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2ebe0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2ebf0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2ec00 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2ec10 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2ec20 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
2ec30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2ec40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ec50 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
2ec60 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
2ec70 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
2ec80 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
2ec90 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2eca0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
2ecb0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
2ecc0 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
2ecd0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
2ece0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
2ecf0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
2ed00 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
2ed10 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
2ed20 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
2ed30 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
2ed40 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
2ed50 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
2ed60 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
2ed70 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
2ed80 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
2ed90 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
2eda0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2edb0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
2edc0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2edd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ede0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2edf0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2ee00 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2ee10 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
2ee20 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
2ee30 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
2ee40 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
2ee50 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
2ee60 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
2ee70 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
2ee80 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
2ee90 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
2eea0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
2eeb0 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
2eec0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2eed0 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2eee0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2eef0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
2ef00 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
2ef10 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
2ef20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2ef30 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2ef40 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
2ef50 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
2ef60 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
2ef70 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
2ef80 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
2ef90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
2efa0 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
2efb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
2efc0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
2efd0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
2efe0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
2eff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f000 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
2f010 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
2f020 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
2f030 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
2f040 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
2f050 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
2f060 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
2f070 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
2f080 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
2f090 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
2f0a0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
2f0b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2f0c0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
2f0d0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
2f0e0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
2f0f0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
2f100 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
2f110 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
2f120 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
2f130 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
2f140 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
2f150 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
2f160 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2f170 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
2f180 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
2f190 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
2f1a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
2f1b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f1c0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
2f1d0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
2f1e0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
2f1f0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
2f200 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
2f210 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
2f220 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
2f230 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
2f240 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
2f250 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
2f260 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
2f270 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
2f280 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
2f290 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
2f2a0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2f2b0 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
2f2c0 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
2f2d0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
2f2e0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
2f2f0 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
2f300 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
2f310 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f320 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
2f330 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
2f340 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
2f350 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
2f360 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2f370 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2f380 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
2f390 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
2f3a0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
2f3b0 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
2f3c0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
2f3d0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
2f3e0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
2f3f0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
2f400 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
2f410 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
2f420 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
2f430 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
2f440 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
2f450 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
2f460 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2f470 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
2f480 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
2f490 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
2f4a0 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
2f4b0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
2f4c0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2f4d0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2f4e0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
2f4f0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
2f500 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
2f510 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
2f520 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2f530 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2f540 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
2f550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f560 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
2f570 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2f580 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
2f590 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
2f5a0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
2f5b0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
2f5c0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
2f5d0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
2f5e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
2f5f0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
2f600 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
2f610 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
2f620 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
2f630 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2f640 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
2f650 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
2f660 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
2f670 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2f680 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
2f690 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2f6a0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
2f6b0 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
2f6c0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2f6d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2f6e0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
2f6f0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
2f700 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2f710 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
2f720 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
2f730 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
2f740 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2f750 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
2f760 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
2f770 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
2f780 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
2f790 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
2f7a0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
2f7b0 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
2f7c0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2f7d0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
2f7e0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
2f7f0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
2f800 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
2f810 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
2f820 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
2f830 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
2f840 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f850 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f860 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
2f870 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
2f880 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2f890 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
2f8a0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2f8b0 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
2f8c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
2f8d0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
2f8e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2f8f0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
2f900 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
2f910 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
2f920 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
2f930 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2f940 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
2f950 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
2f960 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
2f970 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
2f980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f990 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
2f9a0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
2f9b0 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
2f9c0 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
2f9d0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
2f9e0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
2f9f0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2fa00 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
2fa10 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
2fa20 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2fa30 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
2fa40 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
2fa50 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
2fa60 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
2fa70 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
2fa80 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
2fa90 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
2faa0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
2fab0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
2fac0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
2fad0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
2fae0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
2faf0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2fb00 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
2fb10 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
2fb20 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
2fb30 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
2fb40 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
2fb50 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
2fb60 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
2fb70 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
2fb80 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
2fb90 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2fba0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
2fbb0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
2fbc0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
2fbd0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
2fbe0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
2fbf0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
2fc00 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
2fc10 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
2fc20 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2fc30 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
2fc40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2fc50 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
2fc60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2fc70 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2fc80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
2fc90 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
2fca0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
2fcb0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
2fcc0 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
2fcd0 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
2fce0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2fcf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
2fd00 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
2fd10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
2fd20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd30 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
2fd40 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
2fd50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
2fd60 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
2fd70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fd80 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
2fd90 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
2fda0 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
2fdb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fdc0 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
2fdd0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2fde0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
2fdf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2fe00 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
2fe10 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
2fe20 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
2fe30 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
2fe40 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
2fe50 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
2fe60 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
2fe70 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2fe80 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2fe90 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68  API3REF: Find th
2fea0 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
2feb0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
2fec0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2fed0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2fee0 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
2fef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ff00 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
2ff10 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
2ff20 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2ff30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
2ff40 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e    ^If pStmt is N
2ff50 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ULL.** then this
2ff60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ff70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ff80 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72  the first prepar
2ff90 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2ffa0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2ffb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2ffc0 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49  nection pDb.  ^I
2ffd0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
2ffe0 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
2fff0 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
30000 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
30010 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
30020 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
30030 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30040 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
30050 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
30060 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
30070 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
30080 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
30090 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
300a0 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
300b0 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
300c0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
300d0 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73  er..*/.sqlite3_s
300e0 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78  tmt *sqlite3_nex
300f0 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a  t_stmt(sqlite3 *
30100 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  pDb, sqlite3_stm
30110 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
30120 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
30130 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
30140 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
30150 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
30160 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
30170 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
30180 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
30190 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
301a0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
301b0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
301c0 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d  saction is [COMM
301d0 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e  IT | committed].
301e0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
301f0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
30200 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
30210 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
30220 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
30230 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30240 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
30250 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  den..** ^The sql
30260 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
30270 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
30280 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
30290 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
302a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
302b0 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
302c0 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43  tion is [ROLLBAC
302d0 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d  K | rolled back]
302e0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
302f0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
30300 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
30310 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
30320 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
30330 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
30340 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
30350 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
30360 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73  pArg argument is
30370 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
30380 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
30390 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
303a0 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
303b0 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
303c0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
303d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
303e0 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
303f0 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
30400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30410 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
30420 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69  (D,C,P) and sqli
30430 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
30440 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
30450 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  ns.** return the
30460 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
30470 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
30480 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ll of the same f
30490 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68  unction.** on th
304a0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
304b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
304c0 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74  or NULL for.** t
304d0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f  he first call fo
304e0 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20  r each function 
304f0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on D..**.** The 
30500 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
30510 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
30520 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
30530 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
30540 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
30550 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
30560 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
30570 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
30580 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
30590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
305a0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
305b0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
305c0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
305d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
305e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
305f0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
30600 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
30610 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
30620 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
30630 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
30640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30650 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
30660 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
30670 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
30680 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
30690 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
306a0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
306b0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
306c0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  raph..**.** ^Reg
306d0 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
306e0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
306f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
30700 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  **.** ^When the 
30710 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
30720 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74  back routine ret
30730 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b  urns zero, the [
30740 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61  COMMIT].** opera
30750 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20  tion is allowed 
30760 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d  to continue norm
30770 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63  ally.  ^If the c
30780 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65  ommit hook.** re
30790 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
307a0 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54  then the [COMMIT
307b0 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  ] is converted i
307c0 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d  nto a [ROLLBACK]
307d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
307e0 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
307f0 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
30800 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
30810 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
30820 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
30830 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
30840 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
30850 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
30860 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  ack..**.** ^For 
30870 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
30880 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
30890 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
308a0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
308b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
308c0 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
308d0 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
308e0 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
308f0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
30900 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
30910 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
30920 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
30930 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
30940 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
30950 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
30960 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
30970 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
30980 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
30990 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
309a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
309b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  sed..**.** See a
309c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
309d0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20  _update_hook()] 
309e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f  interface..*/.vo
309f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
30a00 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
30a10 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
30a20 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
30a30 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
30a40 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
30a50 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
30a60 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
30a70 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
30a80 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
30a90 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
30aa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
30ab0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
30ac0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
30ad0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
30ae0 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
30af0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30b00 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
30b10 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
30b20 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
30b30 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
30b40 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
30b50 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
30b60 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  deleted..** ^Any
30b70 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
30b80 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
30b90 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
30ba0 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
30bb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30bc0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
30bd0 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  den..**.** ^The 
30be0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
30bf0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
30c00 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
30c10 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
30c20 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
30c30 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
30c40 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  eted..** ^The fi
30c50 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
30c60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
30c70 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
30c80 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
30c90 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
30ca0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68  e_hook()..** ^Th
30cb0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
30cc0 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
30cd0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
30ce0 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
30cf0 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
30d00 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
30d10 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
30d20 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
30d30 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
30d40 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
30d50 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  ed..** ^The thir
30d60 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
30d70 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
30d80 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
30d90 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
30da0 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
30db0 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
30dc0 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
30dd0 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66  d row..** ^The f
30de0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
30df0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30e00 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f  rowid] of the ro
30e10 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61  w..** ^In the ca
30e20 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
30e30 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
30e40 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
30e50 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
30e60 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75  e..**.** ^(The u
30e70 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
30e80 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
30e90 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
30ea0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
30eb0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
30ec0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
30ed0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29  lite_sequence).)
30ee0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ^.**.** ^In the 
30ef0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
30f00 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61  tation, the upda
30f10 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f  te hook.** is no
30f20 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64  t invoked when d
30f30 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20  uplication rows 
30f40 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61  are deleted beca
30f50 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e  use of an.** [ON
30f60 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43   CONFLICT | ON C
30f70 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d  ONFLICT REPLACE]
30f80 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69   clause.  ^Nor i
30f90 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
30fa0 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
30fb0 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
30fc0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
30fd0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
30fe0 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
30ff0 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
31000 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
31010 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
31020 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
31030 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
31040 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
31050 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
31060 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
31070 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
31080 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
31090 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
310a0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
310b0 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
310c0 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
310d0 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
310e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
310f0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
31100 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
31110 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
31120 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
31130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
31140 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
31150 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
31160 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
31170 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31180 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
31190 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
311a0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
311b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
311c0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
311d0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
311e0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
311f0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  aph..**.** ^The 
31200 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
31210 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
31220 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ion.** returns t
31230 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
31240 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
31250 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  call.** on the s
31260 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
31270 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
31280 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
31290 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e  first call on D.
312a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
312b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  the [sqlite3_com
312c0 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20  mit_hook()] and 
312d0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
312e0 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74  k_hook()].** int
312f0 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64  erfaces..*/.void
31300 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   *sqlite3_update
31310 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33  _hook(.  sqlite3
31320 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
31330 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63  id *,int ,char c
31340 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73  onst *,char cons
31350 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  t *,sqlite3_int6
31360 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a  4),.  void*.);..
31370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31380 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
31390 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
313a0 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ache.** KEYWORDS
313b0 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d  : {shared cache}
313c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
313d0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
313e0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
313f0 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
31400 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
31410 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
31420 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
31430 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
31440 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74  ection | connect
31450 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ions].** to the 
31460 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53  same database. S
31470 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
31480 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
31490 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64  t is true.** and
314a0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
314b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c   argument is fal
314c0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63  se.)^.**.** ^Cac
314d0 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
314e0 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
314f0 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ed for an entire
31500 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
31510 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
31520 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
31530 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
31540 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
31550 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
31560 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
31570 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
31580 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
31590 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tely..**.** ^(Th
315a0 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
315b0 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
315c0 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
315d0 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
315e0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
315f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
31600 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
31610 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
31620 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
31630 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
31640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
31650 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
31660 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
31670 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
31680 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
31690 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29  ey were opened.)
316a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ^.**.** ^(This r
316b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
316c0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
316d0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
316e0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
316f0 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ed.** successful
31700 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
31710 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
31720 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a   otherwise.)^.**
31730 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68  .** ^Shared cach
31740 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
31750 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
31760 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
31770 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
31780 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
31790 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
317a0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
317b0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
317c0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
317d0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
317e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a  .**.** See Also:
317f0 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64    [SQLite Shared
31800 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a  -Cache Mode].*/.
31810 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
31820 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
31830 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
31840 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
31850 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
31860 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
31870 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
31880 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
31890 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
318a0 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
318b0 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
318c0 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
318d0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
318e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
318f0 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
31900 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20  base library.   
31910 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
31920 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
31930 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
31940 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
31950 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
31960 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
31970 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  ory..** ^sqlite3
31980 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
31990 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
319a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
319b0 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
319c0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
319d0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
319e0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
319f0 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  uested..** ^The 
31a00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
31a10 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65  memory() routine
31a20 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75   is a no-op retu
31a30 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66  rning zero.** if
31a40 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63   SQLite is not c
31a50 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
31a60 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
31a70 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
31a80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
31a90 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
31aa0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31ab0 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
31ac0 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
31ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31ae0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
31af0 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  mit64() interfac
31b00 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75  e sets and/or qu
31b10 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66  eries the.** sof
31b20 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61  t limit on the a
31b30 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
31b40 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
31b50 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
31b60 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  Lite..** ^SQLite
31b70 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70   strives to keep
31b80 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69   heap memory uti
31b90 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74  lization below t
31ba0 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20  he soft heap.** 
31bb0 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e  limit by reducin
31bc0 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  g the number of 
31bd0 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68  pages held in th
31be0 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20  e page cache.** 
31bf0 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75  as heap memory u
31c00 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73  sages approaches
31c10 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
31c20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
31c30 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65  mit is "soft" be
31c40 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67  cause even thoug
31c50 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73  h SQLite strives
31c60 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f   to stay.** belo
31c70 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20  w the limit, it 
31c80 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20  will exceed the 
31c90 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61  limit rather tha
31ca0 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e  n generate.** an
31cb0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
31cc0 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72  error.  In other
31cd0 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74   words, the soft
31ce0 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20   heap limit .** 
31cf0 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
31d00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
31d10 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
31d20 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
31d30 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68  _limit64() is th
31d40 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
31d50 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
31d60 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
31d70 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67  ll.  ^If the arg
31d80 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74  ument N is negat
31d90 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63  ive.** then no c
31da0 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f  hange is made to
31db0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
31dc0 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68  imit.  Hence, th
31dd0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a  e current.** siz
31de0 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65  e of the soft he
31df0 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20  ap limit can be 
31e00 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e  determined by in
31e10 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
31e20 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
31e30 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67  t64() with a neg
31e40 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ative argument..
31e50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
31e60 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f  gument N is zero
31e70 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68   then the soft h
31e80 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73  eap limit is dis
31e90 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  abled..**.** ^(T
31ea0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31eb0 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63  it is not enforc
31ec0 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ed in the curren
31ed0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
31ee0 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f  .** if one or mo
31ef0 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20  re of following 
31f00 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74  conditions are t
31f10 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rue:.**.** <ul>.
31f20 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74  ** <li> The soft
31f30 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73   heap limit is s
31f40 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c  et to zero..** <
31f50 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75  li> Memory accou
31f60 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  nting is disable
31f70 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e  d using a combin
31f80 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
31f90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
31fa0 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
31fb0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c  NFIG_MEMSTATUS],
31fc0 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20  ...) start-time 
31fd0 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  option and.**   
31fe0 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44     the [SQLITE_D
31ff0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
32000 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
32010 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41  ption..** <li> A
32020 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61  n alternative pa
32030 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
32040 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69  ntation is speci
32050 66 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  fed using.**    
32060 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
32070 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
32080 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a  G_PCACHE],...)..
32090 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65  ** <li> The page
320a0 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73   cache allocates
320b0 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65   from its own me
320c0 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69  mory pool suppli
320d0 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73  ed.**      by [s
320e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
320f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
32100 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61  GECACHE],...) ra
32110 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
32120 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e    from the heap.
32130 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
32140 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68  * Beginning with
32150 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
32160 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20  3.7.3, the soft 
32170 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
32180 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64  forced.** regard
32190 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
321a0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
321b0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
321c0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20  _MANAGEMENT].** 
321d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
321e0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
321f0 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   With [SQLITE_EN
32200 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
32210 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20  GEMENT],.** the 
32220 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
32230 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65  is enforced on e
32240 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
32250 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74  cation.  Without
32260 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
32270 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
32280 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20  MENT], the soft 
32290 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e  heap limit is on
322a0 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77  ly enforced.** w
322b0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  hen memory is al
322c0 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70  located by the p
322d0 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74  age cache.  Test
322e0 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61  ing suggests tha
322f0 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65  t because.** the
32300 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74   page cache is t
32310 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d  he predominate m
32320 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51  emory user in SQ
32330 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70  Lite, most.** ap
32340 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  plications will 
32350 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65  achieve adequate
32360 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32370 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74   enforcement wit
32380 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20  hout.** the use 
32390 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  of [SQLITE_ENABL
323a0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
323b0 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENT]..**.** The 
323c0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e  circumstances un
323d0 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65  der which SQLite
323e0 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68   will enforce th
323f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
32400 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73  t may.** changes
32410 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
32420 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
32430 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
32440 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
32450 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65  p_limit64(sqlite
32460 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a  3_int64 N);../*.
32470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
32480 72 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61  recated Soft Hea
32490 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63  p Limit Interfac
324a0 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  e.** DEPRECATED.
324b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
324c0 64 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69  deprecated versi
324d0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
324e0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
324f0 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  it64()].** inter
32500 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74  face.  This rout
32510 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20  ine is provided 
32520 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
32530 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
32540 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61  only.  All new a
32550 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
32560 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73  ld use the.** [s
32570 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
32580 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65  _limit64()] inte
32590 72 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61  rface rather tha
325a0 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53  n this one..*/.S
325b0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
325c0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f   void sqlite3_so
325d0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
325e0 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t N);.../*.** CA
325f0 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
32600 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
32610 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
32620 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
32630 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
32640 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
32650 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
32660 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
32670 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
32680 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
32690 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
326a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
326b0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
326c0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
326d0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
326e0 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
326f0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
32700 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
32710 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
32720 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
32730 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
32740 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32750 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
32760 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
32770 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
32780 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
32790 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
327a0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
327b0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
327c0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
327d0 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
327e0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
327f0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
32800 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
32810 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
32820 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
32830 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
32840 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
32850 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
32860 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
32870 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
32880 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
32890 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
328a0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
328b0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
328c0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
328d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
328e0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
328f0 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
32900 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
32910 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
32920 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
32930 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
32940 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
32950 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
32960 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
32970 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
32980 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
32990 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
329a0 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
329b0 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
329c0 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
329d0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
329e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
329f0 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
32a00 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
32a10 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
32a20 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
32a30 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
32a40 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
32a50 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
32a60 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
32a70 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
32a80 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
32a90 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
32aa0 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
32ab0 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
32ac0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
32ad0 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
32ae0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32af0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
32b00 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
32b10 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
32b20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
32b30 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
32b40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
32b50 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
32b60 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
32b70 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
32b80 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
32b90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
32ba0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
32bb0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
32bc0 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
32bd0 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
32be0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
32bf0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
32c00 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
32c10 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
32c20 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
32c30 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
32c40 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
32c50 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
32c60 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
32c70 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
32c80 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
32c90 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
32ca0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
32cb0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
32cc0 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
32cd0 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
32ce0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
32cf0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
32d00 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
32d10 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
32d20 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
32d30 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
32d40 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
32d50 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
32d60 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
32d70 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
32d80 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
32d90 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
32da0 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
32db0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
32dc0 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
32dd0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
32de0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
32df0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
32e00 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
32e10 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
32e20 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
32e30 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
32e40 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
32e50 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
32e60 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
32e70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32e80 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
32e90 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
32ea0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
32eb0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
32ec0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
32ed0 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
32ee0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
32ef0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
32f00 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
32f10 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
32f20 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
32f30 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
32f40 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
32f50 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
32f60 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
32f70 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
32f80 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
32f90 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
32fa0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
32fb0 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
32fc0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32fd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
32fe0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
32ff0 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
33000 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
33010 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
33020 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
33030 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
33040 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
33050 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
33060 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
33070 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
33080 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
33090 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
330a0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
330b0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
330c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
330d0 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
330e0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
330f0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
33100 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
33110 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
33120 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
33130 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
33140 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
33150 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
33160 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
33170 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
33180 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
33190 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
331a0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
331b0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
331c0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
331d0 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
331e0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
331f0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
33200 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
33210 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
33220 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
33230 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
33240 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
33250 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
33260 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
33270 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
33280 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
33290 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
332a0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
332b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
332c0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
332d0 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
332e0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
332f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
33300 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
33310 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
33320 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
33330 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
33340 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
33350 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
33360 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33370 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
33380 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
33390 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
333a0 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
333b0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
333c0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
333d0 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
333e0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
333f0 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
33400 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
33410 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
33420 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
33430 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
33440 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
33450 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
33460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33470 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
33480 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33490 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
334a0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
334b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
334c0 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
334d0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
334e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
334f0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
33500 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
33510 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
33520 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
33530 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
33540 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
33550 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
33560 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
33570 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
33580 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
33590 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
335a0 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
335b0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
335c0 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
335d0 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
335e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
335f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
33600 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
33610 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
33620 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
33630 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
33640 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
33650 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
33660 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
33670 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
33680 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
33690 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
336a0 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
336b0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
336c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
336d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
336e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
336f0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
33700 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
33710 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
33720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
33730 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
33740 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
33750 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
33760 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
33770 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
33780 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
33790 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
337a0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
337b0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
337c0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
337d0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
337e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
337f0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
33800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33810 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
33820 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
33830 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
33840 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
33850 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
33860 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
33870 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
33880 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
33890 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
338a0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
338b0 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
338c0 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
338d0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
338e0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
338f0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
33900 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
33910 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
33920 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
33930 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
33940 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
33950 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
33960 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
33970 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
33980 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
33990 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
339a0 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
339b0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
339c0 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
339d0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
339e0 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
339f0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
33a00 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
33a10 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
33a20 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
33a30 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
33a40 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
33a50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
33a60 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
33a70 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
33a80 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
33a90 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63 61  lly Load Statica
33aa0 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e  lly Linked Exten
33ab0 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  sions.**.** ^Thi
33ac0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  s interface caus
33ad0 65 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69  es the xEntryPoi
33ae0 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f  nt() function to
33af0 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a   be invoked for.
33b00 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61 74  ** each new [dat
33b10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33b20 5d 20 74 68 61 74 20 69 73 20 63 72 65 61 74 65  ] that is create
33b30 64 2e 20 20 54 68 65 20 69 64 65 61 20 68 65 72  d.  The idea her
33b40 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e  e is that.** xEn
33b50 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74 68  tryPoint() is th
33b60 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f  e entry point fo
33b70 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20 6c  r a statically l
33b80 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78 74  inked SQLite ext
33b90 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  ension.** that i
33ba0 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74 69  s to be automati
33bb0 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74  cally loaded int
33bc0 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61  o all new databa
33bd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a  se connections..
33be0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f  **.** ^(Even tho
33bf0 75 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ugh the function
33c00 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77 73   prototype shows
33c10 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69 6e   that xEntryPoin
33c20 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20  t() takes.** no 
33c30 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72 65  arguments and re
33c40 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69  turns void, SQLi
33c50 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72  te invokes xEntr
33c60 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74 68  yPoint() with th
33c70 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73  ree.** arguments
33c80 20 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e 64   and expects and
33c90 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
33ca0 61 73 20 69 66 20 74 68 65 20 73 69 67 6e 61 74  as if the signat
33cb0 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e  ure of the.** en
33cc0 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65 20  try point where 
33cd0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
33ce0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
33cf0 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 69  re>.** &nbsp;  i
33d00 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 0a  nt xEntryPoint(.
33d10 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 73 71 6c  ** &nbsp;    sql
33d20 69 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62  ite3 *db,.** &nb
33d30 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 63 68 61  sp;    const cha
33d40 72 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a  r **pzErrMsg,.**
33d50 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74   &nbsp;    const
33d60 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
33d70 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a 70 54  api_routines *pT
33d80 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  hunk.** &nbsp;  
33d90 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
33da0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
33db0 2a 20 49 66 20 74 68 65 20 78 45 6e 74 72 79 50  * If the xEntryP
33dc0 6f 69 6e 74 20 72 6f 75 74 69 6e 65 20 65 6e 63  oint routine enc
33dd0 6f 75 6e 74 65 72 73 20 61 6e 20 65 72 72 6f 72  ounters an error
33de0 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65  , it should make
33df0 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 70 6f   *pzErrMsg.** po
33e00 69 6e 74 20 74 6f 20 61 6e 20 61 70 70 72 6f 70  int to an approp
33e10 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
33e20 61 67 65 20 28 6f 62 74 61 69 6e 65 64 20 66 72  age (obtained fr
33e30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
33e40 6e 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64 20 72  ntf()]).** and r
33e50 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72  eturn an appropr
33e60 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
33e70 5d 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e 73 75  ].  ^SQLite ensu
33e80 72 65 73 20 74 68 61 74 20 2a 70 7a 45 72 72 4d  res that *pzErrM
33e90 73 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 62 65  sg.** is NULL be
33ea0 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 65  fore calling the
33eb0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 2e 20   xEntryPoint(). 
33ec0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e   ^SQLite will in
33ed0 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  voke.** [sqlite3
33ee0 5f 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70 7a 45  _free()] on *pzE
33ef0 72 72 4d 73 67 20 61 66 74 65 72 20 78 45 6e 74  rrMsg after xEnt
33f00 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e  ryPoint() return
33f10 73 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a 20 78  s.  ^If any.** x
33f20 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74  EntryPoint() ret
33f30 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20 74  urns an error, t
33f40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
33f50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
33f60 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  en16()],.** or [
33f70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
33f80 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 70 72 6f  )] call that pro
33f90 76 6f 6b 65 64 20 74 68 65 20 78 45 6e 74 72 79  voked the xEntry
33fa0 50 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66 61 69  Point() will fai
33fb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  l..**.** ^Callin
33fc0 67 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  g sqlite3_auto_e
33fd0 78 74 65 6e 73 69 6f 6e 28 58 29 20 77 69 74 68  xtension(X) with
33fe0 20 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20   an entry point 
33ff0 58 20 74 68 61 74 20 69 73 20 61 6c 72 65 61 64  X that is alread
34000 79 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69 73 74  y.** on the list
34010 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 65 78   of automatic ex
34020 74 65 6e 73 69 6f 6e 73 20 69 73 20 61 20 68 61  tensions is a ha
34030 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e  rmless no-op. ^N
34040 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a  o entry point.**
34050 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
34060 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 66  more than once f
34070 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65  or each database
34080 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
34090 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a   is opened..**.*
340a0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
340b0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
340c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f  extension()]..*/
340d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
340e0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
340f0 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28   (*xEntryPoint)(
34100 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void));../*.** C
34110 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
34120 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
34130 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
34140 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
34150 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61 75   disables all au
34160 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
34170 6e 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ns previously.**
34180 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
34190 67 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  g [sqlite3_auto_
341a0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f  extension()]..*/
341b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
341c0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
341d0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
341e0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
341f0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
34200 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
34210 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
34220 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
34230 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
34240 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
34250 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
34260 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
34270 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
34280 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
34290 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
342a0 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
342b0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
342c0 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
342d0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
342e0 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
342f0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
34300 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
34310 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
34320 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
34330 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
34340 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
34350 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
34360 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
34370 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
34380 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
34390 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
343a0 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
343b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
343c0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
343d0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
343e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
343f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34400 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
34410 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
34420 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
34430 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
34440 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
34450 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
34460 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  able Object.** K
34470 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
34480 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
34490 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
344a0 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
344b0 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
344c0 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
344d0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
344e0 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
344f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34500 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
34510 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
34520 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
34530 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
34540 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
34550 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
34560 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
34570 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
34580 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
34590 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
345a0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
345b0 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
345c0 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
345d0 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
345e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
345f0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
34600 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
34610 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
34620 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
34630 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
34640 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
34650 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
34660 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
34670 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
34680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34690 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
346a0 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
346b0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
346c0 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
346d0 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
346e0 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
346f0 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
34700 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
34710 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
34720 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
34730 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
34740 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
34750 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
34760 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
34770 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
34780 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
34790 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
347a0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
347b0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
347c0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
347d0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
347e0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
347f0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
34800 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
34810 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34820 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
34830 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
34840 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
34850 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
34860 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
34870 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
34880 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
34890 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
348a0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
348b0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
348c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
348d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
348e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
348f0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
34900 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
34910 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
34920 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
34930 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
34940 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
34950 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34960 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
34970 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
34980 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
34990 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
349a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
349b0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
349c0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
349d0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
349e0 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
349f0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
34a00 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
34a10 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
34a20 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
34a30 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
34a40 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
34a50 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
34a60 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
34a70 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
34a80 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
34a90 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
34aa0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
34ab0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
34ac0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
34ad0 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
34ae0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
34af0 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
34b00 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34b10 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
34b20 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
34b30 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
34b40 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
34b50 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34b60 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
34b70 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
34b80 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
34b90 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
34ba0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
34bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34bc0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
34bd0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
34be0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
34bf0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
34c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34c10 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
34c20 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
34c30 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
34c40 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
34c50 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
34c60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
34c70 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
34c80 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
34c90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
34ca0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
34cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34cc0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
34cd0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
34ce0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
34cf0 20 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a   used as part.**
34d00 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
34d10 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63   table] interfac
34d20 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  e to.** pass inf
34d30 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
34d40 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
34d50 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
34d60 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
34d70 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
34d80 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
34d90 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
34da0 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
34db0 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
34dc0 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
34dd0 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
34de0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
34df0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
34e00 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
34e10 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
34e20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
34e30 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
34e40 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
34e50 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
34e60 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
34e70 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
34e80 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c  >column OP expr<
34e90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
34ea0 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d  ** where OP is =
34eb0 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
34ec0 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e  gt;, or &gt;=.)^
34ed0 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c    ^(The particul
34ee0 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a  ar operator is.*
34ef0 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e  * stored in aCon
34f00 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69  straint[].op usi
34f10 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ng one of the.**
34f20 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43   [SQLITE_INDEX_C
34f30 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53  ONSTRAINT_EQ | S
34f40 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
34f50 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e  TRAINT_ values].
34f60 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65  )^.** ^(The inde
34f70 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
34f80 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
34f90 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
34fa0 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e  olumn.)^  ^(aCon
34fb0 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65  straint[].usable
34fc0 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a   is TRUE if the.
34fd0 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72  ** expr on the r
34fe0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63  ight-hand side c
34ff0 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  an be evaluated 
35000 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f  (and thus the co
35010 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75  nstraint.** is u
35020 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65  sable) and false
35030 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e   if it cannot.)^
35040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69  .**.** ^The opti
35050 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
35060 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
35070 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
35080 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
35090 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
350a0 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
350b0 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
350c0 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
350d0 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
350e0 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
350f0 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
35100 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
35110 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
35120 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61  ** ^The aConstra
35130 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
35140 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
35150 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74  lause terms that
35160 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74   are.** relevant
35170 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
35180 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
35190 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
351a0 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69  **.** ^Informati
351b0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44  on about the ORD
351c0 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
351d0 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72  stored in aOrder
351e0 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74  By[]..** ^Each t
351f0 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20  erm of aOrderBy 
35200 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e  records a column
35210 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
35220 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54   clause..**.** T
35230 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20  he [xBestIndex] 
35240 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c  method must fill
35250 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
35260 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  e[] with informa
35270 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68  tion.** about wh
35280 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  at parameters to
35290 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72   pass to xFilter
352a0 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78  .  ^If argvIndex
352b0 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
352c0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
352d0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
352e0 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
352f0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
35300 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
35310 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
35320 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e  ntry in argv.  ^
35330 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  (If aConstraintU
35340 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
35350 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
35360 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
35370 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
35380 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
35390 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
353a0 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
353b0 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
353c0 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  QLite.)^.**.** ^
353d0 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69  The idxNum and i
353e0 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65  dxPtr values are
353f0 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61   recorded and pa
35400 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ssed into the.**
35410 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f   [xFilter] metho
35420 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f  d..** ^[sqlite3_
35430 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20  free()] is used 
35440 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
35450 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
35460 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
35470 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
35480 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e   ^The orderByCon
35490 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
354a0 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46   output from [xF
354b0 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77  ilter]/[xNext] w
354c0 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
354d0 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
354e0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
354f0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35500 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
35510 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
35520 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
35530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74  ..**.** ^The est
35540 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
35550 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
35560 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
35570 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
35580 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
35590 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
355a0 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
355b0 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
355c0 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
355d0 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
355e0 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
355f0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
35600 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
35610 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
35620 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
35630 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
35640 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
35650 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
35660 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
35670 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
35680 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
35690 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
356a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
356b0 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
356c0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
356d0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
356e0 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
356f0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
35700 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
35710 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
35720 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
35730 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
35740 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
35750 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
35760 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
35770 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
35780 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
35790 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
357a0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
357b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
357c0 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
357d0 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
357e0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
357f0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
35800 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
35810 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
35820 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
35830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35840 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
35850 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
35860 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
35870 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
35880 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
35890 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
358a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
358b0 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
358c0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
358d0 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
358e0 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
358f0 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
35900 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
35910 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
35920 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
35930 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f  clause */.  /* O
35940 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
35950 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
35960 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
35970 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
35980 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
35990 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
359a0 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
359b0 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
359c0 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
359d0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
359e0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
359f0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
35a00 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
35a10 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
35a20 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
35a30 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
35a40 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
35a50 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
35a60 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
35a70 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
35a80 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
35a90 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
35aa0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
35ab0 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
35ac0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
35ad0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
35ae0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
35af0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
35b00 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
35b10 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
35b20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
35b30 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
35b40 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
35b50 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
35b60 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
35b70 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
35b80 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
35b90 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
35ba0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
35bb0 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f  ble Constraint O
35bc0 70 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a  perator Codes.**
35bd0 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
35be0 20 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c   defined the all
35bf0 6f 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20  owed values for 
35c00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
35c10 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e  index_info].aCon
35c20 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65  straint[].op fie
35c30 6c 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20  ld.  Each value 
35c40 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e  represents.** an
35c50 20 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69   operator that i
35c60 73 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73  s part of a cons
35c70 74 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74  traint term in t
35c80 68 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20  he wHERE clause 
35c90 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68  of.** a query th
35ca0 61 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75  at uses a [virtu
35cb0 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64  al table]..*/.#d
35cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
35cd0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
35ce0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
35cf0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
35d00 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64  RAINT_GT    4.#d
35d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
35d20 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45  EX_CONSTRAINT_LE
35d30 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
35d40 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
35d50 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23  RAINT_LT    16.#
35d60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
35d70 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
35d80 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
35d90 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
35da0 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34  STRAINT_MATCH 64
35db0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35dc0 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72  : Register A Vir
35dd0 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65  tual Table Imple
35de0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  mentation.**.** 
35df0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
35e00 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69  are used to regi
35e10 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74  ster a new [virt
35e20 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
35e30 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75  ] name..** ^Modu
35e40 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
35e50 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
35e60 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61  re.** creating a
35e70 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
35e80 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d  ble] using the m
35e90 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65  odule and before
35ea0 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65   using a.** pree
35eb0 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c  xisting [virtual
35ec0 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20   table] for the 
35ed0 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  module..**.** ^T
35ee0 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69  he module name i
35ef0 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20  s registered on 
35f00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35f10 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
35f20 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  ied.** by the fi
35f30 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
35f40 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
35f50 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e   module is given
35f60 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f   by the .** seco
35f70 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
35f80 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
35f90 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
35fa0 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65   to.** the imple
35fb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
35fc0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
35fd0 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20  module].   ^The 
35fe0 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
35ff0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
36000 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ary client data 
36010 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
36020 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
36030 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65  * into the [xCre
36040 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
36050 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ct] methods of t
36060 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
36070 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20   module.** when 
36080 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61  a new virtual ta
36090 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20  ble is be being 
360a0 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69  created or reini
360b0 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  tialized..**.** 
360c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
360d0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
360e0 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20  interface has a 
360f0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
36100 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
36110 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72  inter to a destr
36120 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43  uctor for the pC
36130 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c  lientData.  ^SQL
36140 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f  ite will.** invo
36150 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
36160 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69  r function (if i
36170 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77  t is not NULL) w
36180 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f  hen SQLite.** no
36190 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68   longer needs th
361a0 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f  e pClientData po
361b0 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65 73  inter.  ^The des
361c0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73  tructor will als
361d0 6f 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20  o.** be invoked 
361e0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
361f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36200 64 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73 2e  dule_v2() fails.
36210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36220 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
36230 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
36240 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
36250 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36260 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61  dule_v2() with a
36270 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63   NULL.** destruc
36280 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tor..*/.int sqli
36290 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
362a0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
362b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
362c0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
362d0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
362e0 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
362f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
36300 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
36310 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
36320 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
36330 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
36340 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
36350 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
36360 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
36370 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ata          /* 
36380 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
36390 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
363a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
363b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
363c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
363d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
363e0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
363f0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
36400 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
36410 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36420 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
36430 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
36440 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
36450 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
36460 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
36470 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
36480 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
36490 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f  tData,         /
364a0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
364b0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
364c0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
364d0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
364e0 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
364f0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
36500 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
36510 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
36520 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
36530 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
36540 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a  S: sqlite3_vtab.
36550 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
36560 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
36570 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
36580 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
36590 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a  s.** of this obj
365a0 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20  ect to describe 
365b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
365c0 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20  tance.** of the 
365d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
365e0 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
365f0 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f  will.** be tailo
36600 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
36610 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
36620 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
36630 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70  tation..** The p
36640 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
36650 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
36660 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
36670 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a  ields that are.*
36680 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  * common to all 
36690 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
366a0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56  ations..**.** ^V
366b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
366c0 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
366d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
366e0 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
366f0 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
36700 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36710 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72  printf()] to zEr
36720 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
36730 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
36740 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
36750 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
36760 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
36770 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
36780 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61  )].** prior to a
36790 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73  ssigning a new s
367a0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67  tring to zErrMsg
367b0 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72  .  ^After the er
367c0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
367d0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
367e0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
367f0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
36800 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
36810 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
36820 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
36830 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
36840 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
36850 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73   be zeroed..*/.s
36860 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
36870 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
36880 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
36890 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
368a0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
368b0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
368c0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
368d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
368e0 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53   /* NO LONGER US
368f0 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45  ED */.  char *zE
36900 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20  rrMsg;          
36910 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
36920 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71   message from sq
36930 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
36940 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
36950 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
36960 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
36970 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
36980 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
36990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
369a0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
369b0 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a  Cursor Object.**
369c0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
369d0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
369e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
369f0 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72  rsor}.**.** Ever
36a00 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
36a10 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
36a20 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
36a30 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
36a40 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  * following stru
36a50 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62  cture to describ
36a60 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
36a70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  oint into the.**
36a80 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
36a90 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
36aa0 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
36ab0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
36ac0 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
36ad0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
36ae0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
36af0 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f  odule.xOpen | xO
36b00 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  pen] method of t
36b10 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72  he module and ar
36b20 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62  e destroyed.** b
36b30 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  y the [sqlite3_m
36b40 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78  odule.xClose | x
36b50 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20  Close] method.  
36b60 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64  Cursors are used
36b70 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c  .** by the [xFil
36b80 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b  ter], [xNext], [
36b90 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d  xEof], [xColumn]
36ba0 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d  , and [xRowid] m
36bb0 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65  ethods.** of the
36bc0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
36bd0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
36be0 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
36bf0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
36c00 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
36c10 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
36c20 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
36c30 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
36c40 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
36c50 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
36c60 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
36c70 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
36c80 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
36c90 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
36ca0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
36cb0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
36cc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
36cd0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
36ce0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
36cf0 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
36d00 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
36d10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
36d20 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
36d30 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
36d40 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
36d50 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
36d60 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
36d70 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
36d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72  .**.** ^The [xCr
36d90 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
36da0 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
36db0 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  a.** [virtual ta
36dc0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c  ble module] call
36dd0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a   this interface.
36de0 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
36df0 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
36e00 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
36e10 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
36e20 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
36e30 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
36e40 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
36e50 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
36e60 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
36e70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51   const char *zSQ
36e80 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  L);../*.** CAPI3
36e90 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20  REF: Overload A 
36ea0 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56  Function For A V
36eb0 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
36ec0 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62  ** ^(Virtual tab
36ed0 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
36ee0 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
36ef0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
36f00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
36f10 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63  g the [xFindFunc
36f20 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  tion] method of 
36f30 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
36f40 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a  le module].  .**
36f50 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
36f60 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
36f70 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
36f80 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
36f90 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
36fa0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
36fb0 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
36fc0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
36fd0 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
36fe0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
36ff0 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
37000 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
37010 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
37020 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
37030 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
37040 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
37050 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
37060 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20  n is created.)^ 
37070 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
37080 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
37090 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
370a0 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
370b0 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
370c0 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
370d0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
370e0 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
370f0 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
37100 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
37110 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
37120 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e   placeholder fun
37130 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
37140 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
37150 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  by a [virtual ta
37160 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ble]..*/.int sql
37170 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75  ite3_overload_fu
37180 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c  nction(sqlite3*,
37190 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
371a0 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67  ncName, int nArg
371b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
371c0 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
371d0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
371e0 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61  hanism defined a
371f0 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a  bove (back up.**
37200 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65   to a comment re
37210 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72  markably similar
37220 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73   to this one) is
37230 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
37240 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
37250 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
37260 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
37270 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
37280 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
37290 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
372a0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
372b0 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
372c0 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
372d0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
372e0 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
372f0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
37300 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
37310 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
37320 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
37330 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
37340 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
37350 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
37360 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt..*/../*.** CA
37370 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
37380 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
37390 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42  .** KEYWORDS: {B
373a0 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f  LOB handle} {BLO
373b0 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a  B handles}.**.**
373c0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
373d0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
373e0 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42  esents an open B
373f0 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  LOB on which.** 
37400 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
37410 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
37420 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62   BLOB I/O] can b
37430 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20  e performed..** 
37440 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73  ^Objects of this
37450 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65   type are create
37460 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
37470 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  ob_open()].** an
37480 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  d destroyed by [
37490 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
374a0 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b  se()]..** ^The [
374b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
374c0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
374d0 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
374e0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61  interfaces.** ca
374f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61  n be used to rea
37500 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c  d or write small
37510 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20   subsections of 
37520 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68  the BLOB..** ^Th
37530 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
37540 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
37550 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
37560 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
37570 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70  in bytes..*/.typ
37580 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
37590 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33  te3_blob sqlite3
375a0 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _blob;../*.** CA
375b0 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42  PI3REF: Open A B
375c0 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e  LOB For Incremen
375d0 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28  tal I/O.**.** ^(
375e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20  This interfaces 
375f0 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61  opens a [BLOB ha
37600 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74  ndle | handle] t
37610 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74  o the BLOB locat
37620 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f  ed.** in row iRo
37630 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d  w, column zColum
37640 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20  n, table zTable 
37650 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b  in database zDb;
37660 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  .** in other wor
37670 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f  ds, the same BLO
37680 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20  B that would be 
37690 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
376a0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
376b0 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
376c0 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
376d0 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69  HERE [rowid] = i
376e0 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  Row;.** </pre>)^
376f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
37700 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
37710 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
37720 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
37730 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20  ned for read.** 
37740 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
37750 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f  . ^If it is zero
37760 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70  , the BLOB is op
37770 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63  ened for read ac
37780 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  cess..** ^It is 
37790 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
377a0 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
377b0 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e  at is part of an
377c0 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72   index or primar
377d0 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72  y .** key for wr
377e0 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65  iting. ^If [fore
377f0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
37800 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  nts] are enabled
37810 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20  , it is .** not 
37820 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
37830 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
37840 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69  s part of a [chi
37850 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74  ld key] for writ
37860 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ing..**.** ^Note
37870 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
37880 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74  se name is not t
37890 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74  he filename that
378a0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
378b0 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61   database but ra
378c0 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69  ther the symboli
378d0 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  c name of the da
378e0 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61  tabase that.** a
378f0 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65  ppears after the
37900 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e   AS keyword when
37910 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
37920 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67   connected using
37930 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46   [ATTACH]..** ^F
37940 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
37950 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64  base file, the d
37960 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
37970 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20  "main"..** ^For 
37980 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
37990 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
379a0 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
379b0 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  ^(On success, [S
379c0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
379d0 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
379e0 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  w [BLOB handle] 
379f0 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  is written.** to
37a00 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77   *ppBlob. Otherw
37a10 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
37a20 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
37a30 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73  and *ppBlob is s
37a40 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75  et.** to be a nu
37a50 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a  ll pointer.)^.**
37a60 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
37a70 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61  sets the [databa
37a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65  se connection] e
37a90 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
37aa0 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
37ab0 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
37ac0 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
37ad0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
37ae0 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a  )] and related.*
37af0 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f  * functions. ^No
37b00 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42  te that the *ppB
37b10 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20  lob variable is 
37b20 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a  always initializ
37b30 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74  ed in a.** way t
37b40 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66  hat makes it saf
37b50 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
37b60 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
37b70 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a  )] on *ppBlob.**
37b80 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
37b90 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  he success or fa
37ba0 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f  ilure of this ro
37bb0 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  utine..**.** ^(I
37bc0 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61  f the row that a
37bd0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69   BLOB handle poi
37be0 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69  nts to is modifi
37bf0 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44  ed by an.** [UPD
37c00 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20  ATE], [DELETE], 
37c10 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49  or by [ON CONFLI
37c20 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73  CT] side-effects
37c30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  .** then the BLO
37c40 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b  B handle is mark
37c50 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e  ed as "expired".
37c60 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65  .** This is true
37c70 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f   if any column o
37c80 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61  f the row is cha
37c90 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c  nged, even a col
37ca0 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  umn.** other tha
37cb0 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c  n the one the BL
37cc0 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65  OB handle is ope
37cd0 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c  n on.)^.** ^Call
37ce0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  s to [sqlite3_bl
37cf0 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
37d00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
37d10 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65  te()] for.** a e
37d20 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64  xpired BLOB hand
37d30 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  le fail with an 
37d40 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
37d50 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
37d60 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74  * ^(Changes writ
37d70 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ten into a BLOB 
37d80 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f  prior to the BLO
37d90 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e  B expiring are n
37da0 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  ot.** rolled bac
37db0 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74  k by the expirat
37dc0 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ion of the BLOB.
37dd0 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77    Such changes w
37de0 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  ill eventually.*
37df0 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20  * commit if the 
37e00 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
37e10 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
37e20 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73  ion.)^.**.** ^Us
37e30 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  e the [sqlite3_b
37e40 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
37e50 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d  erface to determ
37e60 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  ine the size of.
37e70 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c  ** the opened bl
37e80 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f  ob.  ^The size o
37e90 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74  f a blob may not
37ea0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74   be changed by t
37eb0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
37ec0 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41  .  Use the [UPDA
37ed0 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  TE] SQL command 
37ee0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69  to change the si
37ef0 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e  ze of a.** blob.
37f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
37f10 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
37f20 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ob()] and [sqlit
37f30 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
37f40 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ob()] interfaces
37f50 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c  .** and the buil
37f60 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20  t-in [zeroblob] 
37f70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  SQL function can
37f80 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73   be used, if des
37f90 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61  ired,.** to crea
37fa0 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72  te an empty, zer
37fb0 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e  o-filled blob in
37fc0 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f   which to read o
37fd0 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a  r write using.**
37fe0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
37ff0 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
38000 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c  a resource leak,
38010 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f   every open [BLO
38020 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64  B handle] should
38030 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62   eventually.** b
38040 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20  e released by a 
38050 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
38060 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
38070 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
38080 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
38090 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
380a0 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
380b0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
380c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
380d0 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
380e0 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
380f0 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
38100 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
38110 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
38120 52 45 46 3a 20 4d 6f 76 65 20 61 20 42 4c 4f 42  REF: Move a BLOB
38130 20 48 61 6e 64 6c 65 20 74 6f 20 61 20 4e 65 77   Handle to a New
38140 20 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   Row.**.** ^This
38150 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
38160 64 20 74 6f 20 6d 6f 76 65 20 61 6e 20 65 78 69  d to move an exi
38170 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c  sting blob handl
38180 65 20 73 6f 20 74 68 61 74 20 69 74 20 70 6f 69  e so that it poi
38190 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 64 69 66 66  nts.** to a diff
381a0 65 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  erent row of the
381b0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 74   same database t
381c0 61 62 6c 65 2e 20 5e 54 68 65 20 6e 65 77 20 72  able. ^The new r
381d0 6f 77 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  ow is identified
381e0 0a 2a 2a 20 62 79 20 74 68 65 20 72 6f 77 69 64  .** by the rowid
381f0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
38200 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
38210 6d 65 6e 74 2e 20 4f 6e 6c 79 20 74 68 65 20 72  ment. Only the r
38220 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20 63 68 61  ow can be.** cha
38230 6e 67 65 64 2e 20 5e 54 68 65 20 64 61 74 61 62  nged. ^The datab
38240 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63  ase, table and c
38250 6f 6c 75 6d 6e 20 6f 6e 20 77 68 69 63 68 20 74  olumn on which t
38260 68 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69  he blob handle i
38270 73 20 6f 70 65 6e 0a 2a 2a 20 72 65 6d 61 69 6e  s open.** remain
38280 20 74 68 65 20 73 61 6d 65 2e 20 4d 6f 76 69 6e   the same. Movin
38290 67 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c  g an existing bl
382a0 6f 62 20 68 61 6e 64 6c 65 20 74 6f 20 61 20 6e  ob handle to a n
382b0 65 77 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a  ew row can be.**
382c0 20 66 61 73 74 65 72 20 74 68 61 6e 20 63 6c 6f   faster than clo
382d0 73 69 6e 67 20 74 68 65 20 65 78 69 73 74 69 6e  sing the existin
382e0 67 20 68 61 6e 64 6c 65 20 61 6e 64 20 6f 70 65  g handle and ope
382f0 6e 69 6e 67 20 61 20 6e 65 77 20 6f 6e 65 2e 0a  ning a new one..
38300 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 6e 65 77 20  **.** ^(The new 
38310 72 6f 77 20 6d 75 73 74 20 6d 65 65 74 20 74 68  row must meet th
38320 65 20 73 61 6d 65 20 63 72 69 74 65 72 69 61 20  e same criteria 
38330 61 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  as for [sqlite3_
38340 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a 2a  blob_open()] -.*
38350 2a 20 69 74 20 6d 75 73 74 20 65 78 69 73 74 20  * it must exist 
38360 61 6e 64 20 74 68 65 72 65 20 6d 75 73 74 20 62  and there must b
38370 65 20 65 69 74 68 65 72 20 61 20 62 6c 6f 62 20  e either a blob 
38380 6f 72 20 74 65 78 74 20 76 61 6c 75 65 20 73 74  or text value st
38390 6f 72 65 64 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ored in.** the n
383a0 6f 6d 69 6e 61 74 65 64 20 63 6f 6c 75 6d 6e 2e  ominated column.
383b0 29 5e 20 5e 49 66 20 74 68 65 20 6e 65 77 20 72  )^ ^If the new r
383c0 6f 77 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e  ow is not presen
383d0 74 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2c 20  t in the table, 
383e0 6f 72 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  or if.** it does
383f0 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20 62   not contain a b
38400 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c 75  lob or text valu
38410 65 2c 20 6f 72 20 69 66 20 61 6e 6f 74 68 65 72  e, or if another
38420 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 61   error occurs, a
38430 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72 6f  n.** SQLite erro
38440 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
38450 65 64 20 61 6e 64 20 74 68 65 20 62 6c 6f 62 20  ed and the blob 
38460 68 61 6e 64 6c 65 20 69 73 20 63 6f 6e 73 69 64  handle is consid
38470 65 72 65 64 20 61 62 6f 72 74 65 64 2e 0a 2a 2a  ered aborted..**
38480 20 5e 41 6c 6c 20 73 75 62 73 65 71 75 65 6e 74   ^All subsequent
38490 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
384a0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2c  e3_blob_read()],
384b0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
384c0 72 69 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  rite()] or.** [s
384d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70  qlite3_blob_reop
384e0 65 6e 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72  en()] on an abor
384f0 74 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20  ted blob handle 
38500 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
38510 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 42 4f  rn.** SQLITE_ABO
38520 52 54 2e 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  RT. ^Calling [sq
38530 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
38540 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74 65  ()] on an aborte
38550 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65 0a 2a 2a  d blob handle.**
38560 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
38570 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  zero..**.** ^Thi
38580 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
38590 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  the database han
385a0 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  dle error code a
385b0 6e 64 20 6d 65 73 73 61 67 65 2e 0a 2a 2f 0a 53  nd message..*/.S
385c0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
385d0 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  AL int sqlite3_b
385e0 6c 6f 62 5f 72 65 6f 70 65 6e 28 73 71 6c 69 74  lob_reopen(sqlit
385f0 65 33 5f 62 6c 6f 62 20 2a 2c 20 73 71 6c 69 74  e3_blob *, sqlit
38600 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
38610 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
38620 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a  e A BLOB Handle.
38630 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e  **.** ^Closes an
38640 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
38650 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  le]..**.** ^Clos
38660 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
38670 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
38680 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
38690 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
386a0 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
386b0 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
386c0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
386d0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
386e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
386f0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61  nection is in [a
38700 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e  utocommit mode].
38710 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69 74  .** ^If any writ
38720 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
38730 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
38740 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
38750 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
38760 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
38770 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
38780 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f  fit..**.** ^(Clo
38790 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66  sing the BLOB of
387a0 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63  ten forces the c
387b0 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f  hanges.** out to
387c0 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20   disk and so if 
387d0 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f  any I/O errors o
387e0 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20  ccur, they will 
387f0 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20  likely occur.** 
38800 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
38810 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   the BLOB is clo
38820 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73  sed.  Any errors
38830 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
38840 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
38850 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
38860 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
38870 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  value.)^.**.** ^
38880 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f  (The BLOB is clo
38890 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  sed unconditiona
388a0 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68  lly.  Even if th
388b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
388c0 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  ns.** an error c
388d0 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ode, the BLOB i