/ Hex Artifact Content
Login

Artifact e047f69a61d604d4f8be6cf1d1bdfc68be9ba7e5:


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 74 79 70  sqlite3_vfs;.typ
a4c0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
a4d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
a4e0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
a4f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
a500: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
a510: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
a520: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
a530: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
a540: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
a550: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
a560: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
a570: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
a580: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
a590: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
a5a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
a5b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
a5c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
a5d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
a5e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
a5f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
a600: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
a610: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
a620: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
a630: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
a640: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
a650: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
a660: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
a670: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
a680: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
a690: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a6a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a6b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
a6c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
a6d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
a6e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
a6f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
a700: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
a710: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
a720: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
a730: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
a740: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
a750: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
a760: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
a770: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
a780: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
a790: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
a7a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
a7b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
a7c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
a7d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
a7e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
a7f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
a800: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
a810: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a820: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
a830: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
a840: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
a850: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
a860: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
a870: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
a880: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
a890: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a8a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
a8b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
a8c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
a8d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
a8e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
a8f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
a900: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
a910: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
a920: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
a930: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
a940: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
a950: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
a960: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
a970: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
a980: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
a990: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
a9a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
a9b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
a9c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
a9d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
a9e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
a9f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
aa00: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
aa10: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
aa20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
aa30: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
aa40: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
aa50: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
aa60: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
aa70: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
aa80: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
aa90: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
aaa0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
aab0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
aac0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
aad0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
aae0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
aaf0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ab00: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ab10: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ab20: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ab30: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ab40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ab50: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ab60: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ab70: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ab80: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ab90: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
aba0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
abb0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
abc0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
abd0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
abe0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
abf0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
ac00: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
ac10: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
ac20: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
ac30: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
ac40: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
ac50: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
ac60: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
ac70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
ac80: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
ac90: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
aca0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
acb0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
acc0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
acd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ace0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
acf0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ad00: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ad10: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ad20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ad30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ad40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ad50: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ad60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ad70: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ad80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ad90: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ada0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
adb0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
adc0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
add0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
ade0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
adf0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ae00: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ae10: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
ae20: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ae30: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
ae40: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
ae50: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
ae60: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
ae70: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
ae80: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
ae90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
aea0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
aeb0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
aec0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
aed0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
aee0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
aef0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
af00: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
af10: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
af20: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
af30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
af40: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
af50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
af60: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
af70: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
af80: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
af90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
afa0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
afb0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
afc0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
afd0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
afe0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
aff0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
b000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
b010: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
b020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b030: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
b040: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
b050: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
b060: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
b070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
b080: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
b090: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
b0a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b0b0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
b0c0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
b0d0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
b0e0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
b0f0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
b100: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
b110: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
b120: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
b130: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
b140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
b150: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
b160: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
b170: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
b180: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
b190: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
b1a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
b1b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
b1c0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
b1d0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
b1e0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b1f0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
b200: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
b210: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b220: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
b230: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
b240: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
b250: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
b260: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
b280: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
b290: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
b2a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
b2b0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
b2c0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
b2d0: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73  en no the corres
b2e0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
b2f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
b300: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
b310: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
b320: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
b330: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
b340: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
b350: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
b360: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
b370: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
b380: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
b390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
b3a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
b3b0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
b3c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
b3d0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b3e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
b3f0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
b400: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
b410: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
b420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
b430: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
b440: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
b450: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
b460: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
b470: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
b480: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
b490: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
b4a0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
b4b0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
b4c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
b4d0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
b4e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
b4f0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
b500: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
b510: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
b520: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b530: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
b540: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
b550: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
b560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
b570: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
b580: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b590: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
b5a0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
b5b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
b5c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
b5d0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
b5e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
b5f0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
b600: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
b610: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
b620: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
b630: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
b640: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
b650: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
b660: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
b670: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
b680: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
b690: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
b6a0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
b6b0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
b6c0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
b6d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
b6e0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
b6f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
b700: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b710: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
b720: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
b730: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
b740: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
b750: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b760: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
b770: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
b780: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
b790: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
b7a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
b7b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b7c0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
b7d0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
b7e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b7f0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
b800: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
b810: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
b820: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
b830: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
b840: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
b850: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
b860: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
b870: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
b880: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b890: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
b8a0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
b8b0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
b8c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
b8d0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
b8e0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
b8f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
b900: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
b910: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
b920: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b930: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
b940: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
b950: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
b960: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b970: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
b980: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
b990: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
b9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b9b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
b9c0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
b9d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b9e0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
b9f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ba00: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
ba10: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
ba20: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
ba30: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
ba40: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
ba50: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
ba60: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
ba70: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
ba80: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
ba90: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
baa0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
bab0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
bac0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
bad0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
bae0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
baf0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
bb00: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
bb10: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
bb20: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
bb30: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
bb40: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
bb50: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
bb60: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
bb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
bb80: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
bb90: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
bba0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
bbb0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
bbc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bbd0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
bbe0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
bbf0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
bc00: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
bc10: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
bc20: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
bc30: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
bc40: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
bc50: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
bc60: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
bc70: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
bc80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bc90: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
bca0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
bcb0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
bcc0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
bcd0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
bce0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
bcf0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
bd00: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
bd10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bd20: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
bd30: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
bd40: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
bd50: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
bd60: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
bd70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
bd80: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
bd90: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
bda0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
bdb0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
bdc0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
bdd0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
bde0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
bdf0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
be00: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
be10: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
be20: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
be30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
be40: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
be50: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
be60: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
be70: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
be80: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
be90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
bea0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
beb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
bec0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
bed0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
bee0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
bef0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
bf00: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
bf10: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
bf20: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
bf30: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
bf40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bf50: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
bf60: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
bf70: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
bf80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
bf90: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
bfa0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
bfb0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
bfc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
bfd0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
bfe0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
bff0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c000: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
c010: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
c020: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
c030: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
c040: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
c050: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
c060: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
c070: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
c080: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
c090: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
c0a0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
c0b0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
c0c0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
c0d0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
c0e0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
c0f0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
c100: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
c110: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
c120: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
c130: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
c140: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
c150: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
c160: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
c170: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
c180: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
c190: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
c1a0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
c1b0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
c1c0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
c1d0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
c1e0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
c1f0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
c200: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
c210: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
c220: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c230: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
c240: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
c250: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
c260: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
c270: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
c280: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c290: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
c2a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c2b0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
c2c0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
c2d0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
c2e0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
c2f0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
c300: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
c310: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c320: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
c330: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
c340: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
c350: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
c360: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
c370: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
c380: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
c390: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
c3a0: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
c3b0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
c3c0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
c3d0: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
c3e0: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
c3f0: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
c400: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
c410: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
c420: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
c430: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
c440: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
c450: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
c460: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
c470: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
c480: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
c490: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
c4a0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
c4b0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
c4c0: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
c4d0: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
c4e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
c4f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c500: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
c510: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
c520: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
c530: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
c540: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
c550: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
c560: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
c570: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c580: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
c590: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
c5a0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
c5b0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
c5c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
c5d0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
c5e0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c5f0: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
c600: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
c610: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
c620: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
c630: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
c640: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
c650: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
c660: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
c670: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
c680: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
c690: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
c6a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
c6b0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
c6c0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
c6d0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
c6e0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
c6f0: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
c700: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
c710: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
c720: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
c730: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
c740: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
c750: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
c760: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
c770: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
c780: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
c790: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
c7a0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
c7b0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
c7c0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
c7d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
c7e0: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
c7f0: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
c800: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
c810: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
c820: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
c830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
c840: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
c850: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
c860: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
c870: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
c880: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c890: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
c8a0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
c8b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
c8c0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
c8d0: 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
c8e0: 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
c8f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
c900: 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
c910: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
c920: 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
c930: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
c940: 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
c950: 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
c960: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
c970: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
c980: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
c990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
c9a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
c9b0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
c9c0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
c9d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
c9e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
c9f0: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
ca00: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
ca10: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ca20: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
ca30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
ca40: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
ca50: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
ca60: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
ca70: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
ca80: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
ca90: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
caa0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
cab0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
cac0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
cad0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
cae0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
caf0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
cb00: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
cb10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
cb20: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
cb30: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
cb40: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
cb50: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
cb60: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
cb70: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
cb80: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
cb90: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
cba0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
cbb0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
cbc0: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
cbd0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
cbe0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
cbf0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
cc00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cc10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
cc20: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cc30: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
cc40: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
cc50: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
cc60: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
cc70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cc80: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
cc90: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
cca0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ccb0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ccc0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ccd0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
cce0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ccf0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
cd00: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
cd10: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
cd20: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
cd30: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
cd40: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
cd50: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
cd60: 51 4c 49 54 45 5f 44 42 43 4f 4e 49 47 5f 4c 4f  QLITE_DBCONIG_LO
cd70: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
cd80: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
cd90: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
cda0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
cdb0: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
cdc0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
cdd0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
cde0: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
cdf0: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
ce00: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
ce10: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
ce20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
ce30: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
ce40: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
ce50: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
ce60: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
ce70: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
ce80: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
ce90: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
cea0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
ceb0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
cec0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
ced0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
cee0: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
cef0: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
cf00: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
cf10: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
cf20: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
cf30: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
cf40: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
cf50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cf60: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
cf70: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
cf80: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
cf90: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
cfa0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
cfb0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
cfc0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
cfd0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
cfe0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
cff0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
d000: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
d010: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d020: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
d030: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
d040: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
d050: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
d060: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
d070: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
d080: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
d090: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
d0a0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
d0b0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
d0c0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
d0d0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
d0e0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d0f0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
d100: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
d110: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d120: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
d130: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
d140: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
d150: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
d160: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
d170: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
d180: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
d190: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
d1a0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
d1b0: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
d1c0: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
d1d0: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
d1e0: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
d1f0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
d200: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
d210: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
d220: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
d230: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
d240: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
d250: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
d260: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
d270: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
d280: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
d290: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
d2a0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
d2b0: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
d2c0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
d2d0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
d2e0: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
d2f0: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
d300: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
d310: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
d320: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
d330: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
d340: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
d350: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
d360: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
d370: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
d380: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
d390: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
d3a0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
d3b0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
d3c0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
d3d0: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
d3e0: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
d3f0: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
d400: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
d410: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
d420: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
d430: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
d440: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
d450: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
d460: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
d470: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
d480: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
d490: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
d4a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
d4b0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
d4c0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
d4d0: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
d4e0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
d4f0: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
d500: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
d510: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
d520: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
d530: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
d540: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
d550: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
d560: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
d570: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
d580: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
d590: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
d5a0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
d5b0: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
d5c0: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
d5d0: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
d5e0: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
d5f0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
d600: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
d610: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
d620: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
d630: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
d640: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
d650: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
d660: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
d670: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
d680: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
d690: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
d6a0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
d6b0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
d6c0: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
d6d0: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
d6e0: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
d6f0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d700: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
d710: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
d720: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
d730: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
d740: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
d750: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
d760: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
d770: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
d780: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
d790: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
d7a0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
d7b0: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
d7c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
d7d0: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
d7e0: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
d7f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
d800: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
d810: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
d820: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
d830: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
d840: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
d850: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
d860: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
d870: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
d880: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
d890: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
d8a0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
d8b0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
d8c0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
d8d0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d8e0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
d8f0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
d900: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
d910: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
d920: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
d930: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
d940: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
d950: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d960: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
d970: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d980: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d990: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d9a0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d9b0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d9c0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d9d0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d9e0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d9f0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
da00: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
da10: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
da20: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
da30: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
da40: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
da50: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
da60: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
da70: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
da80: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
da90: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
daa0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
dab0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
dac0: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
dad0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
dae0: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
daf0: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
db00: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
db10: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
db20: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
db30: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
db40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
db50: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
db60: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
db70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
db80: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
db90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dba0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
dbb0: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
dbc0: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
dbd0: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
dbe0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
dbf0: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
dc00: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
dc10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
dc20: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
dc30: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
dc40: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
dc50: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
dc60: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
dc70: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
dc80: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
dc90: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
dca0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
dcb0: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
dcc0: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
dcd0: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
dce0: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
dcf0: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
dd00: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
dd10: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
dd20: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
dd30: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
dd40: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
dd50: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
dd60: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
dd70: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
dd80: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
dd90: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
dda0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
ddb0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
ddc0: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
ddd0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
dde0: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
ddf0: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
de00: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
de10: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
de20: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
de30: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
de40: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
de50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
de60: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
de70: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
de80: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
de90: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
dea0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
deb0: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
dec0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
ded0: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
dee0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
def0: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
df00: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
df10: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
df20: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
df30: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
df40: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
df50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
df60: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
df70: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
df80: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
df90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
dfa0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
dfb0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
dfc0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
dfd0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
dfe0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
dff0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
e000: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
e010: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
e020: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
e030: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
e040: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
e050: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
e060: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
e070: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
e080: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
e090: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
e0a0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e0b0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
e0c0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
e0d0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
e0e0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
e0f0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
e100: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e110: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
e120: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
e130: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
e140: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e150: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
e160: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
e170: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
e180: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
e190: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
e1a0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
e1b0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
e1c0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
e1d0: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
e1e0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
e1f0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
e200: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
e210: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
e220: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
e230: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
e240: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
e250: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
e260: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
e270: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
e280: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
e290: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
e2a0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
e2b0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
e2c0: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
e2d0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
e2e0: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
e2f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
e300: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
e310: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
e320: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
e330: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
e340: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
e350: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
e360: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
e370: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
e380: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
e390: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
e3a0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
e3b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e3c0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
e3d0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
e3e0: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
e3f0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e400: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
e410: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e420: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
e430: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e440: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
e450: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
e460: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
e470: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
e480: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
e490: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
e4a0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
e4b0: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
e4c0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e4d0: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
e4e0: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
e4f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e500: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
e510: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
e520: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
e530: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
e540: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
e550: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
e560: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
e570: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
e580: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
e590: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
e5a0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
e5b0: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
e5c0: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
e5d0: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
e5e0: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
e5f0: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
e600: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
e610: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
e620: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
e630: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e640: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
e650: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
e660: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e670: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e680: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
e690: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
e6a0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
e6b0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
e6c0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
e6d0: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
e6e0: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
e6f0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
e700: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
e710: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
e720: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
e730: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
e740: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
e750: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
e760: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
e770: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
e780: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e790: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e7a0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e7b0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e7c0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e7d0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e7e0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e7f0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e800: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
e810: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
e820: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
e830: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
e840: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
e850: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
e860: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
e870: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
e880: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
e890: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
e8a0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
e8b0: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
e8c0: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
e8d0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e8e0: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
e8f0: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
e900: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
e910: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
e920: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
e930: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
e940: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
e950: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e960: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
e970: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
e980: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
e990: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
e9a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
e9b0: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
e9c0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
e9d0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
e9e0: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
e9f0: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
ea00: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
ea10: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
ea20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
ea30: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
ea40: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
ea50: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
ea60: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
ea70: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
ea80: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
ea90: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
eaa0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
eab0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
eac0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
ead0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
eae0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
eaf0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
eb00: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
eb10: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
eb20: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
eb30: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
eb40: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
eb50: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
eb60: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
eb70: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
eb80: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
eb90: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
eba0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
ebb0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ebc0: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
ebd0: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
ebe0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
ebf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ec00: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
ec10: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
ec20: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
ec30: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
ec40: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
ec50: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
ec60: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
ec70: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
ec80: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
ec90: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
eca0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
ecb0: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
ecc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ecd0: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
ece0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ecf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ed00: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
ed10: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
ed20: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
ed30: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ed40: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ed50: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
ed60: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
ed70: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
ed80: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
ed90: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
eda0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
edb0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
edc0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
edd0: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
ede0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
edf0: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
ee00: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
ee10: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
ee20: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
ee30: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
ee40: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
ee50: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
ee60: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
ee70: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
ee80: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
ee90: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
eea0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
eeb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
eec0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
eed0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
eee0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
eef0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
ef00: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
ef10: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
ef20: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
ef30: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
ef40: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
ef50: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
ef60: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
ef70: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
ef80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ef90: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
efa0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
efb0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
efc0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
efd0: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
efe0: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
eff0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
f000: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
f010: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f020: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
f030: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
f040: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
f050: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
f060: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f070: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
f080: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
f090: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f0a0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
f0b0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
f0c0: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
f0d0: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
f0e0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
f0f0: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
f100: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
f110: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
f120: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
f130: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
f140: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
f150: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f160: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f170: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
f180: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
f190: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
f1a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
f1b0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
f1c0: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
f1d0: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
f1e0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
f1f0: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
f200: 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
f210: 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
f220: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
f230: 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f  scrach allocatio
f240: 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
f250: 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
f260: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
f270: 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
f280: 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
f290: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
f2a0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
f2b0: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
f2c0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
f2d0: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
f2e0: 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
f2f0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
f300: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
f310: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
f320: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
f330: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
f340: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
f350: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
f360: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
f370: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
f380: 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
f390: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
f3a0: 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
f3b0: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
f3c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
f3d0: 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
f3e0: 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
f3f0: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
f400: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
f410: 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
f420: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
f430: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
f440: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
f450: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
f460: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
f470: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
f480: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
f490: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f4a0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
f4b0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
f4c0: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
f4d0: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
f4e0: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
f4f0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f500: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
f510: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
f520: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
f530: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
f540: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
f550: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
f560: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
f570: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
f580: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
f590: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
f5a0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
f5b0: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
f5c0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
f5d0: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
f5e0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
f5f0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
f600: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
f610: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
f620: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
f630: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
f640: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
f650: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
f660: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
f670: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
f680: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
f690: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
f6a0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
f6b0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
f6c0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
f6d0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
f6e0: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
f6f0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
f700: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
f710: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
f720: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
f730: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
f740: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
f750: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
f760: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
f770: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
f780: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
f790: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
f7a0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
f7b0: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
f7c0: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
f7d0: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
f7e0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
f7f0: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
f800: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
f810: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
f820: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
f830: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
f840: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
f850: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
f860: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
f870: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
f880: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
f890: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f8a0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
f8b0: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
f8c0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
f8d0: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
f8e0: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
f8f0: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
f900: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
f910: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
f920: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
f930: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
f940: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
f950: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
f960: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
f970: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
f980: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
f990: 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
f9a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f9b0: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
f9c0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f9d0: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
f9e0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
f9f0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
fa00: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
fa10: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
fa20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fa30: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
fa40: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
fa50: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
fa60: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
fa70: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
fa80: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
fa90: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
faa0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fab0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
fac0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
fad0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
fae0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
faf0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
fb00: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
fb10: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
fb20: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
fb30: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
fb40: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
fb50: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
fb60: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
fb70: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
fb80: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
fb90: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
fba0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
fbb0: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
fbc0: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
fbd0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
fbe0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
fbf0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
fc00: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
fc10: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
fc20: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
fc30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
fc40: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
fc50: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
fc60: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fc70: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
fc80: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
fc90: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
fca0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
fcb0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
fcc0: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
fcd0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
fce0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
fcf0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
fd00: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
fd10: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
fd20: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
fd30: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
fd40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
fd50: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
fd60: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
fd70: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
fd80: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
fd90: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
fda0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
fdb0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
fdc0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
fdd0: 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
fde0: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
fdf0: 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
fe00: 70 65 64 20 61 74 20 32 5e 31 32 2e 20 52 65 61  ped at 2^12. Rea
fe10: 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
fe20: 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
fe30: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
fe40: 65 20 61 72 65 20 32 5e 35 20 74 68 72 6f 75 67  e are 2^5 throug
fe50: 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  h 2^8.</dd>.**.*
fe60: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
fe70: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
fe80: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
fe90: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
fea0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
feb0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
fec0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
fed0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
fee0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
fef0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ff00: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
ff10: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
ff20: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
ff30: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
ff40: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
ff50: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
ff60: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
ff70: 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
ff80: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
ff90: 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
ffa0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
ffb0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ffc0: 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
ffd0: 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
ffe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
fff0: 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
10000 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10010 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
10020 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10030 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
10040 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
10050 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
10060 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
10070 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
10080 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
10090 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
100a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
100b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
100c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
100d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
100e0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
100f0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
10100 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
10110 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
10120 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
10130 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
10140 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10150 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10160 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10170 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10180 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
10190 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
101a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
101b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
101c0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
101d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
101e0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
101f0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10200 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10210 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
10220 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
10230 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
10240 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
10250 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
10260 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
10270 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
10280 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
10290 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
102a0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
102b0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
102c0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
102d0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
102e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
102f0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10300 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10310 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10320 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10330 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
10340 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
10350 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
10360 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
10370 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
10380 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
10390 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
103a0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
103b0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
103c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
103d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
103e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
103f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
10400 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10410 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
10420 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10430 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
10440 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
10450 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
10460 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
10470 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68  llocation for th
10480 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
10490 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20  ry allocator on 
104a0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
104b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
104c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
104d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
104e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
104f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
10500 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
10510 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
10520 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
10530 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
10540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
10550 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  ^  ^(This option
10560 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e   sets the.** <i>
10570 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
10580 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
10590 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
105a0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76  _LOOKASIDE].** v
105b0 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  erb to [sqlite3_
105c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
105d0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
105e0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
105f0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
10600 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
10610 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
10620 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
10630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
10640 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10650 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
10660 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
10670 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
10680 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
10690 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
106a0 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
106b0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
106c0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
106d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
106e0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
106f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
10700 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
10710 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
10720 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
10730 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
10740 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
10750 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
10760 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
10770 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
10780 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
10790 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
107a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
107b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
107c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
107d0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
107e0 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
107f0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
10800 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
10810 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
10820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
10830 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
10840 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
10850 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
10860 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
10870 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
10880 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
10890 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
108a0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
108b0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
108c0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
108d0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
108e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
108f0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
10900 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
10910 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
10920 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
10930 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
10940 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
10950 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
10960 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
10970 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
10980 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
10990 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
109a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
109b0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
109c0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
109d0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
109e0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
109f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10a00 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
10a10 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
10a20 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
10a30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10a40 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
10a50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
10a60 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
10a70 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
10a80 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
10a90 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
10aa0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
10ab0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10ac0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
10ad0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10ae0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
10af0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
10b00 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
10b10 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
10b20 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
10b30 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
10b40 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10b50 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
10b60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
10b70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
10b80 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
10b90 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
10ba0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
10bb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
10bc0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
10bd0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
10be0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
10bf0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
10c00 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
10c10 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
10c20 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
10c30 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
10c40 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
10c50 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10c60 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
10c70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
10c80 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
10c90 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
10ca0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
10cb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
10cc0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10cd0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10ce0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
10cf0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
10d00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10d10 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
10d20 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10d40 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
10d50 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10d70 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
10d80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10d90 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10da0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
10db0 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
10dc0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
10dd0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
10de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10df0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
10e00 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
10e10 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
10e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10e30 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
10e40 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
10e50 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
10e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10e70 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
10e80 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
10e90 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
10ea0 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
10eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10ec0 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
10ed0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
10ee0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10ef0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
10f00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
10f10 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
10f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10f30 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
10f40 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
10f50 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
10f60 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
10f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
10f80 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
10f90 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
10fa0 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
10fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
10fc0 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
10fd0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
10fe0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10ff0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
11000 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
11010 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
11020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11030 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
11040 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65     15  /* sqlite
11050 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
11060 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
11070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
11080 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
11090 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a  Func, void* */..
110a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
110b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
110c0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
110d0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
110e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
110f0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11100 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11110 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11120 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11130 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
11140 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
11160 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11170 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11180 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11190 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
111a0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
111b0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
111c0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
111d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
111e0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
111f0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11200 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11210 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11220 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11230 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11240 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
11250 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
11260 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
11270 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11280 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
11290 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
112a0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
112b0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
112c0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
112d0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
112e0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
112f0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
11300 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
11310 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11320 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
11330 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
11340 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
11350 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
11360 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
11370 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
11380 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
11390 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
113a0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
113b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
113c0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
113d0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
113e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
113f0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11400 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
11410 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d  ointer to an mem
11420 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
11430 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
11440 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
11450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
11460 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
11470 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
11480 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
11490 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
114a0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
114b0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
114c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
114d0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
114e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
114f0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
11500 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
11510 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
11520 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
11530 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
11540 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
11550 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
11560 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
11570 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
11580 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11590 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
115a0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
115b0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
115c0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
115d0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
115e0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
115f0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
11600 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
11610 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
11620 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
11630 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
11640 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11650 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
11660 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
11670 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
11680 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
11690 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
116a0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
116b0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
116c0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
116d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
116e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
116f0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
11700 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
11710 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
11720 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
11730 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
11740 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
11750 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
11760 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
11770 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
11780 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11790 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
117a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
117b0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
117c0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
117d0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
117e0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
117f0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
11800 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
11810 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
11820 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
11830 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
11840 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
11850 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
11860 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
11870 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
11880 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
11890 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
118a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
118b0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
118c0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
118d0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
118e0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
118f0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
11900 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
11910 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
11920 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
11930 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
11940 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
11950 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
11960 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
11970 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
11980 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
11990 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
119a0 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
119b0 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
119c0 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
119d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
119e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
119f0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
11a00 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
11a10 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
11a20 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
11a30 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
11a40 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
11a50 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
11a60 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
11a70 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
11a80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
11a90 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
11aa0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
11ab0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
11ac0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
11ad0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
11ae0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
11af0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
11b00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11b10 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
11b20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
11b30 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
11b40 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
11b50 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
11b60 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
11b70 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
11b80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11b90 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
11ba0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
11bb0 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
11bc0 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
11bd0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 65 72 73  o enable trigers
11be0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
11bf0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
11c00 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
11c10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
11c20 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
11c30 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
11c40 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
11c50 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
11c60 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
11c70 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
11c80 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
11c90 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
11ca0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
11cb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11cc0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
11cd0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
11ce0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
11cf0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
11d00 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
11d10 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
11d20 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
11d30 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
11d40 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
11d50 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
11d60 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
11d70 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
11d80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
11d90 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
11da0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
11db0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11dc0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
11dd0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
11de0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
11df0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
11e00 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
11e10 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
11e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11e30 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
11e40 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
11e50 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
11e60 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
11e70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
11e80 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
11e90 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
11ea0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
11eb0 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
11ec0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
11ed0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
11ee0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
11ef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
11f00 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
11f10 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
11f20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
11f30 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
11f40 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
11f50 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
11f60 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
11f70 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
11f80 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
11f90 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
11fa0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
11fb0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
11fc0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
11fd0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
11fe0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
11ff0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
12000 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
12010 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
12020 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
12030 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
12040 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
12050 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
12060 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
12070 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
12080 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
12090 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
120a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
120b0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
120c0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
120d0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
120e0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
120f0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
12100 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
12110 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
12120 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
12130 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
12140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
12150 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12160 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
12170 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
12180 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
12190 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
121a0 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
121b0 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
121c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
121d0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
121e0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
121f0 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
12200 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
12210 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
12220 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
12230 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
12240 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
12250 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
12260 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
12270 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
12280 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
12290 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
122a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
122b0 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
122c0 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
122d0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
122e0 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
122f0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
12300 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
12310 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
12320 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
12330 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
12340 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
12350 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
12360 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12370 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
12380 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
12390 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
123a0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
123b0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
123c0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
123d0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
123e0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
123f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
12400 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
12410 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
12420 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
12430 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
12440 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
12450 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
12460 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
12470 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
12480 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
12490 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
124a0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
124b0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
124c0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
124d0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
124e0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
124f0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
12500 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
12510 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
12520 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
12530 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
12540 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
12550 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
12560 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
12570 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
12580 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
12590 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
125a0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
125b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
125c0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
125d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
125e0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
125f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
12600 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12610 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12620 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
12630 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
12640 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
12650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12660 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
12670 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
12680 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
12690 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
126a0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
126b0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
126c0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
126d0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
126e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
126f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
12700 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
12710 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12720 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
12730 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
12740 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
12750 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
12760 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
12770 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
12780 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
12790 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
127a0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
127b0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
127c0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
127d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
127e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
127f0 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
12800 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
12810 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
12820 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
12830 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
12840 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
12850 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
12860 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
12870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
12880 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
12890 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
128a0 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
128b0 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
128c0 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
128d0 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
128e0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
128f0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
12900 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
12910 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
12920 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
12930 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
12940 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
12950 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
12960 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
12970 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
12980 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
12990 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
129a0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
129b0 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
129c0 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
129d0 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
129e0 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
129f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
12a00 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
12a10 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
12a20 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
12a30 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
12a40 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
12a50 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
12a60 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
12a70 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
12a80 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
12a90 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
12aa0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
12ab0 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
12ac0 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
12ad0 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
12ae0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
12af0 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
12b00 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
12b10 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
12b20 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
12b30 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
12b40 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
12b50 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
12b60 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
12b70 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
12b80 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
12b90 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
12ba0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
12bb0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
12bc0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
12bd0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
12be0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
12bf0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
12c00 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
12c10 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
12c20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
12c30 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
12c40 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
12c50 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
12c60 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
12c70 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
12c80 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
12c90 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
12ca0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
12cb0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
12cc0 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
12cd0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
12ce0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
12cf0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
12d00 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
12d10 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
12d20 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
12d30 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
12d40 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
12d50 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
12d60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
12d70 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
12d80 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
12d90 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
12da0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
12db0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
12dc0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12dd0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
12de0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
12df0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
12e00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
12e10 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
12e20 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
12e30 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
12e40 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
12e50 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
12e60 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
12e70 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
12e80 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
12e90 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
12ea0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
12eb0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
12ec0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
12ed0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
12ee0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
12ef0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
12f00 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
12f10 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
12f20 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
12f30 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
12f40 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
12f50 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
12f60 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
12f70 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
12f80 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
12f90 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
12fa0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
12fb0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
12fc0 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
12fd0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
12fe0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
12ff0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
13000 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
13010 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
13020 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
13030 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
13040 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
13050 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
13060 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
13070 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
13080 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
13090 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
130a0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
130b0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
130c0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
130d0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
130e0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
130f0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
13100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13110 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
13120 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
13130 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
13140 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13150 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
13160 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
13170 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
13180 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
13190 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
131a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
131b0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
131c0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
131d0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
131e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
131f0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
13200 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
13210 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
13220 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
13230 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
13240 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13250 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
13260 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
13270 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
13280 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
13290 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
132a0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
132b0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
132c0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
132d0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
132e0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
132f0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13300 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
13310 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
13320 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13330 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
13340 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
13350 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
13360 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
13370 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
13380 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
13390 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
133a0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
133b0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
133c0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
133d0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
133e0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
133f0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
13400 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
13410 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
13420 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
13430 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
13440 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
13450 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
13460 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13470 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
13480 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
13490 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
134a0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
134b0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
134c0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
134d0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
134e0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
134f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
13500 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
13510 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
13520 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
13530 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
13540 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
13550 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
13560 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
13570 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
13580 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
13590 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
135a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
135b0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
135c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
135d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
135e0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
135f0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13600 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
13610 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
13620 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
13630 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
13640 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
13650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
13660 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
13670 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
13680 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
13690 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
136a0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
136b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
136c0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
136d0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
136e0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
136f0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
13700 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
13710 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
13720 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
13730 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
13740 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
13750 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
13760 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
13770 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
13780 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
13790 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
137a0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
137b0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
137c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
137d0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
137e0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
137f0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
13800 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
13810 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
13820 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
13830 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
13840 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
13850 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
13860 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
13870 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
13880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
13890 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
138a0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
138b0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
138c0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
138d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
138e0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
138f0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
13900 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
13910 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
13920 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
13930 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
13940 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
13950 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
13960 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
13970 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
13980 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
13990 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
139a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
139b0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
139c0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
139d0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
139e0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
139f0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
13a00 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
13a10 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
13a20 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
13a30 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
13a40 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
13a50 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
13a60 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
13a70 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
13a80 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
13a90 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
13aa0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13ab0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
13ac0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
13ad0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
13ae0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
13af0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
13b00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
13b10 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
13b20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
13b30 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
13b40 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
13b50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
13b60 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
13b70 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
13b80 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
13b90 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
13ba0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
13bb0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
13bc0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
13bd0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
13be0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
13bf0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
13c00 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
13c10 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
13c20 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
13c30 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
13c40 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
13c50 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
13c60 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
13c70 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
13c80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
13c90 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
13ca0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
13cb0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
13cc0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
13cd0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
13ce0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
13cf0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
13d00 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
13d10 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
13d20 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
13d30 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
13d40 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
13d50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13d60 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
13d70 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
13d80 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
13d90 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
13da0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
13db0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
13dc0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
13dd0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
13de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13df0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
13e00 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
13e10 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
13e20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
13e30 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
13e40 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
13e50 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
13e60 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
13e70 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
13e80 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
13e90 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
13ea0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
13eb0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
13ec0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
13ed0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
13ee0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
13ef0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
13f00 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
13f10 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
13f20 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
13f30 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
13f40 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
13f50 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
13f60 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
13f70 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
13f80 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
13f90 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
13fa0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
13fb0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
13fc0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
13fd0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
13fe0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
13ff0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
14000 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
14010 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
14020 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
14030 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
14040 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
14050 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
14060 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
14070 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
14080 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
14090 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
140a0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
140b0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
140c0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
140d0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
140e0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
140f0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
14100 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
14110 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
14120 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
14130 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
14140 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
14150 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
14160 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
14170 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
14180 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
14190 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
141a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
141b0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
141c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
141d0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
141e0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
141f0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
14200 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
14210 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
14220 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
14230 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
14240 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
14250 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
14260 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
14270 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
14280 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
14290 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
142a0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
142b0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
142c0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
142d0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
142e0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
142f0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
14300 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
14310 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
14320 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
14330 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
14340 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14350 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
14360 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
14370 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
14380 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
14390 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
143a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
143b0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
143c0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
143d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
143e0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
143f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
14400 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
14410 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
14420 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
14430 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14440 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
14450 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
14460 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
14470 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
14480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
14490 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
144a0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
144b0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
144c0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
144d0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
144e0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
144f0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
14500 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
14510 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
14520 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
14530 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
14540 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
14550 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
14560 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
14570 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
14580 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
14590 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
145a0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
145b0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
145c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
145d0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
145e0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
145f0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
14600 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
14610 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
14620 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
14630 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
14640 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
14650 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14660 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
14670 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
14680 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
14690 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
146a0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
146b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
146c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
146d0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
146e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
146f0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14700 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
14710 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
14720 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
14730 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
14740 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
14750 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
14760 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14770 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
14780 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
14790 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
147a0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
147b0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
147c0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
147d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
147e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
147f0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
14800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
14810 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
14820 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
14830 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
14840 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
14850 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
14860 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
14870 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
14880 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
14890 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
148a0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
148b0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
148c0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
148d0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
148e0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
148f0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
14900 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
14910 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
14920 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
14930 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
14940 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
14950 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
14960 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
14970 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
14980 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
14990 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
149a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
149b0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
149c0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
149d0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
149e0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
149f0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
14a00 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
14a10 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
14a20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
14a30 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
14a40 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
14a50 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
14a60 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
14a70 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
14a80 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
14a90 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
14aa0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
14ab0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
14ac0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
14ad0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
14ae0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
14af0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
14b00 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
14b10 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
14b20 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
14b30 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
14b40 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14b50 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
14b60 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
14b70 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
14b80 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
14b90 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
14ba0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
14bb0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
14bc0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
14bd0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
14be0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
14bf0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
14c00 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
14c10 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
14c20 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
14c30 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14c40 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
14c50 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
14c60 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
14c70 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
14c80 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
14c90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
14ca0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
14cb0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
14cc0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
14cd0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
14ce0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
14cf0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
14d00 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
14d10 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
14d20 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
14d30 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
14d40 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
14d50 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
14d60 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
14d70 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
14d80 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
14d90 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
14da0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
14db0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
14dc0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
14dd0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
14de0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
14df0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
14e00 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
14e10 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
14e20 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
14e30 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
14e40 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
14e50 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
14e60 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
14e70 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
14e80 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
14e90 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
14ea0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
14eb0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
14ec0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
14ed0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
14ee0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
14ef0 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
14f00 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
14f10 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
14f20 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
14f30 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
14f40 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
14f50 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
14f60 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
14f70 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
14f80 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
14f90 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
14fa0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
14fb0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
14fc0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
14fd0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
14fe0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
14ff0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
15000 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15010 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
15020 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
15030 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
15040 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
15050 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
15060 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
15070 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
15080 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
15090 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
150a0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
150b0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
150c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
150d0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
150e0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
150f0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
15100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15110 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
15120 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
15130 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
15140 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
15150 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
15160 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
15170 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
15180 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
15190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
151a0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
151b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
151c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
151d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
151e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
151f0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
15200 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
15210 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
15220 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
15230 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
15240 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15250 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
15260 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
15270 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
15280 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
15290 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
152a0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
152b0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
152c0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
152d0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
152e0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
152f0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
15300 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
15310 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
15320 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
15330 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
15340 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
15350 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
15360 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
15370 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
15380 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
15390 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
153a0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
153b0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
153c0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
153d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
153e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
153f0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
15400 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
15410 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
15420 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
15430 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
15440 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
15450 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
15460 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
15470 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15490 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
154a0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
154b0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
154c0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
154d0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
154e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
154f0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
15500 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
15510 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
15520 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
15530 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
15540 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
15550 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
15560 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
15570 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
15580 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
15590 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
155a0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
155b0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
155c0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
155d0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
155e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
155f0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
15600 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
15610 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
15620 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
15630 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
15640 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
15650 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
15660 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
15670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
15680 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
15690 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
156a0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
156b0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
156c0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
156d0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
156e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
156f0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
15700 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
15710 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
15720 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
15730 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
15740 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
15750 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
15760 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
15770 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
15780 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
15790 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
157a0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
157b0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
157c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
157d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
157e0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
157f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
15800 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
15810 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
15820 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
15830 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
15840 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
15850 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
15860 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
15870 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
15880 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
15890 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
158a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
158b0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
158c0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
158d0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
158e0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
158f0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
15900 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
15910 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
15920 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
15930 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
15940 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
15950 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
15960 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
15970 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
15980 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
15990 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
159a0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
159b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
159c0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
159d0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
159e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
159f0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
15a00 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
15a10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
15a20 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
15a30 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
15a40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
15a50 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
15a60 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
15a70 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
15a80 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
15a90 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
15aa0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15ab0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15ac0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
15ad0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
15ae0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
15af0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15b00 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
15b10 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
15b20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
15b30 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
15b40 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
15b50 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
15b60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15b70 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
15b80 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
15b90 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
15ba0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
15bb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
15bc0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
15bd0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
15be0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
15bf0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
15c00 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
15c10 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
15c20 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
15c30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15c40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
15c50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15c60 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
15c70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
15c80 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
15c90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15ca0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
15cb0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
15cc0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
15cd0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
15ce0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
15cf0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
15d00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15d10 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
15d20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15d30 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
15d40 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
15d50 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
15d60 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
15d70 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
15d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
15d90 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
15da0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
15db0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
15dc0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
15dd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
15de0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
15df0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
15e00 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
15e10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
15e20 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
15e30 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
15e40 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
15e50 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
15e60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
15e70 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
15e80 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
15e90 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
15ea0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
15eb0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
15ec0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
15ed0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
15ee0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
15ef0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
15f00 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
15f10 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
15f20 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
15f30 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
15f40 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
15f50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
15f60 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
15f70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
15f80 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
15f90 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
15fa0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
15fb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
15fc0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
15fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
15fe0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
15ff0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
16000 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
16010 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
16020 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
16030 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
16040 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
16050 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
16060 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
16070 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
16080 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
16090 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
160a0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
160b0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
160c0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
160d0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
160e0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
160f0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
16100 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
16110 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
16120 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
16130 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
16140 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
16150 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
16160 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
16170 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
16180 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
16190 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
161a0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
161b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
161c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
161d0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
161e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
161f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
16200 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
16210 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
16220 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
16230 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
16240 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
16250 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
16260 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
16270 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
16280 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
16290 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
162a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
162b0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
162c0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
162d0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
162e0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
162f0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
16300 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
16310 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
16320 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
16330 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16340 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
16350 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
16360 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
16370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
16380 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
16390 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
163a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
163b0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
163c0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
163d0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
163e0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
163f0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
16400 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
16410 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16420 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
16430 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
16440 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
16450 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
16460 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
16470 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
16480 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
16490 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
164a0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
164b0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
164c0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
164d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
164e0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
164f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
16500 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
16510 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
16520 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
16530 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
16540 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
16550 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
16560 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
16570 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
16580 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
16590 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
165a0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
165b0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
165c0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
165d0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
165e0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
165f0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
16600 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16610 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
16620 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
16630 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
16640 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
16650 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
16660 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
16670 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
16680 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
16690 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
166a0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
166b0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
166c0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
166d0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
166e0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
166f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
16700 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
16710 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16720 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
16730 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
16740 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
16750 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16760 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
16770 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
16780 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
16790 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
167a0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
167b0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
167c0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
167d0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
167e0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
167f0 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
16800 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
16810 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
16820 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
16830 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
16840 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16850 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
16860 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
16870 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
16880 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
16890 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
168a0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
168b0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
168c0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
168d0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
168e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
168f0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
16900 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
16910 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
16920 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
16930 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
16940 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
16950 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
16960 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
16970 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
16980 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
16990 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
169a0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
169b0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
169c0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
169d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
169e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
169f0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
16a00 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
16a10 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
16a20 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
16a30 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
16a40 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
16a50 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
16a60 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
16a70 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
16a80 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
16a90 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
16aa0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
16ab0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
16ac0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
16ad0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
16ae0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
16af0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
16b00 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
16b10 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
16b20 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
16b30 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
16b40 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
16b50 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
16b60 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
16b70 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
16b80 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
16b90 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
16ba0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
16bb0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
16bc0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
16bd0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
16be0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
16bf0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
16c00 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
16c10 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
16c20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
16c30 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
16c40 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
16c50 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16c60 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16c70 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
16c80 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
16c90 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
16ca0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
16cb0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
16cc0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
16cd0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
16ce0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
16cf0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16d00 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
16d10 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
16d20 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
16d30 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
16d40 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
16d50 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
16d60 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
16d70 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
16d80 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
16d90 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16da0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
16db0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
16dc0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
16dd0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
16de0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
16df0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
16e00 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
16e10 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
16e20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16e30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
16e40 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
16e50 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
16e60 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
16e70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16e80 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
16e90 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
16ea0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
16eb0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
16ec0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
16ed0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
16ee0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
16ef0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
16f00 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
16f10 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
16f20 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
16f30 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
16f40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16f50 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
16f60 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
16f70 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
16f80 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
16f90 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
16fa0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
16fb0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
16fc0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
16fd0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
16fe0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
16ff0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
17000 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
17010 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
17020 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
17030 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
17040 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
17050 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
17060 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
17070 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
17080 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
17090 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
170a0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
170b0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
170c0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
170d0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
170e0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
170f0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
17100 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17110 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
17120 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
17130 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
17140 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
17150 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
17160 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
17170 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
17180 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
17190 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
171a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
171b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
171c0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
171d0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
171e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
171f0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
17200 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
17210 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
17220 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
17230 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
17240 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
17250 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
17260 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
17270 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
17280 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
17290 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
172a0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
172b0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
172c0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
172d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
172e0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
172f0 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
17300 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
17310 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
17320 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
17330 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
17340 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
17350 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
17360 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
17370 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
17380 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
17390 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
173a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
173b0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
173c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
173d0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
173e0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
173f0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
17400 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
17410 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
17420 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
17430 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
17440 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
17450 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
17460 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
17470 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
17480 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
17490 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
174a0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
174b0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
174c0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
174d0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
174e0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
174f0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
17500 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
17510 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
17520 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
17530 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
17540 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
17550 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
17560 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
17570 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
17580 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
17590 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
175a0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
175b0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
175c0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
175d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
175e0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
175f0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
17600 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
17610 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
17620 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
17630 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
17640 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
17650 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
17660 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
17670 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
17680 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
17690 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
176a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
176b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
176c0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
176d0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
176e0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
176f0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
17700 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
17710 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
17720 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
17730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17740 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
17750 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
17760 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
17770 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
17780 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
17790 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
177a0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
177b0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
177c0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
177d0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
177e0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
177f0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
17800 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
17810 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
17820 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
17830 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
17840 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
17850 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17860 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
17870 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
17880 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
17890 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
178a0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
178b0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
178c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
178d0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
178e0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
178f0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17900 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
17910 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
17920 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
17930 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
17940 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
17950 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
17960 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
17970 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17980 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
17990 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
179a0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
179b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
179c0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
179d0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
179e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
179f0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17a00 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17a10 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17a20 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17a30 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
17a40 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
17a50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17a60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17a70 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
17a80 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
17a90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17aa0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
17ab0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
17ac0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
17ad0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
17ae0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
17af0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
17b00 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
17b10 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17b20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17b30 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
17b40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17b50 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
17b60 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17b70 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
17b80 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17b90 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
17ba0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
17bb0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
17bc0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
17bd0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
17be0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17bf0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
17c00 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
17c10 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17c20 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
17c30 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
17c40 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
17c50 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
17c60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
17c70 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17c80 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
17c90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
17ca0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
17cb0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
17cc0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
17cd0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
17ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
17cf0 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17d00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17d10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17d20 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17d30 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
17d40 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
17d50 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
17d60 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
17d70 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
17d80 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
17d90 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
17da0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
17db0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
17dc0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
17dd0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
17de0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
17df0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
17e00 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
17e10 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
17e20 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
17e30 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
17e40 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
17e50 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
17e60 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
17e70 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
17e80 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
17e90 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
17ea0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
17eb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17ec0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
17ed0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
17ee0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
17ef0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
17f00 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
17f10 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
17f20 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
17f30 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
17f40 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
17f50 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
17f60 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
17f70 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
17f80 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
17f90 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
17fa0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
17fb0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
17fc0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
17fd0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
17fe0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
17ff0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
18000 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
18010 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
18020 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
18030 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
18040 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
18050 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
18060 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
18070 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
18080 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
18090 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
180a0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
180b0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
180c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
180d0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
180e0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
180f0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
18100 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
18110 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
18120 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
18130 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
18140 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
18150 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
18160 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
18170 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
18180 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
18190 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
181a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
181b0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
181c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
181d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
181e0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
181f0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
18200 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
18210 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
18220 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
18230 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
18240 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
18250 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
18260 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
18270 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
18280 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
18290 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
182a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
182b0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
182c0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
182d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
182e0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
182f0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
18300 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
18310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
18320 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
18330 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
18340 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
18350 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
18360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
18370 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
18380 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
18390 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
183a0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
183b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
183c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
183d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
183e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
183f0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
18400 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18410 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
18420 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
18430 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
18440 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18450 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18460 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18470 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
18480 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
18490 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
184a0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
184b0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
184c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
184d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
184e0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
184f0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
18500 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
18510 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
18520 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
18530 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
18540 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
18550 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
18560 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
18570 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
18580 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
18590 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
185a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
185b0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
185c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
185d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
185e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
185f0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
18600 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18610 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
18620 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18630 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
18640 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
18650 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
18660 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
18670 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18680 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
18690 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
186a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
186b0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
186c0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
186d0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
186e0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
186f0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
18700 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
18710 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
18720 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
18730 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
18740 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
18750 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
18760 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
18770 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
18780 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
18790 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
187a0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
187b0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
187c0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
187d0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
187e0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
187f0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
18800 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
18810 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
18820 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
18830 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
18840 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
18850 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
18860 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
18870 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
18880 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
18890 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
188a0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
188b0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
188c0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
188d0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
188e0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
188f0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
18900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
18910 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
18920 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
18930 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
18940 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
18950 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
18960 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
18970 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
18980 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
18990 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
189a0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
189b0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
189c0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
189d0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
189e0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
189f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
18a00 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
18a10 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
18a20 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
18a30 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
18a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18a50 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
18a60 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
18a70 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
18a80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
18a90 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69  isters a authori
18aa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
18ab0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
18ac0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18ad0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
18ae0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
18af0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
18b00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18b20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
18b30 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
18b40 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
18b50 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
18b60 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
18b70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18b80 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
18b90 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
18ba0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
18bb0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
18bc0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
18bd0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
18be0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
18bf0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
18c00 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
18c10 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
18c20 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
18c30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18c40 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18c50 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
18c60 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
18c70 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
18c80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18c90 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
18ca0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
18cb0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
18cc0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
18cd0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
18ce0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
18cf0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
18d00 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
18d10 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
18d20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
18d30 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
18d40 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
18d50 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
18d60 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
18d70 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
18d80 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
18d90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18da0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
18db0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
18dc0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
18dd0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
18de0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
18df0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
18e00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18e10 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
18e20 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
18e30 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
18e40 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
18e50 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
18e60 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
18e70 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
18e80 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18e90 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
18ea0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
18eb0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
18ec0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
18ed0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18ee0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
18ef0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
18f00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
18f10 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
18f20 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
18f30 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
18f40 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
18f50 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
18f60 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
18f70 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
18f80 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
18f90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
18fa0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
18fb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
18fc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
18fd0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
18fe0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
18ff0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
19000 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
19010 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19020 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
19030 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
19040 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
19050 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
19060 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
19070 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
19080 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
19090 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
190a0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
190b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
190c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
190d0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
190e0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
190f0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
19100 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
19110 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
19120 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
19130 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
19140 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
19150 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
19160 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
19170 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
19180 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
19190 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
191a0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
191b0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
191c0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
191d0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
191e0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
191f0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
19200 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
19210 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
19220 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
19230 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
19240 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
19250 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
19260 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
19270 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
19280 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
19290 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
192a0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
192b0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
192c0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
192d0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
192e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
192f0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
19300 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
19310 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
19320 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
19330 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
19340 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
19350 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
19360 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
19370 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
19380 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
19390 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
193a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
193b0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
193c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
193d0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
193e0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
193f0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
19400 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19410 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
19420 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
19430 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
19440 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
19450 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
19460 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
19470 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
19480 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
19490 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
194a0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
194b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
194c0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
194d0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
194e0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
194f0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
19500 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
19510 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
19520 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
19530 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
19540 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
19550 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
19560 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
19570 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
19580 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
19590 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
195a0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
195b0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
195c0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
195d0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
195e0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
195f0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
19600 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
19610 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
19620 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
19630 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
19640 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
19650 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
19660 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
19670 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
19680 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
19690 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
196a0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
196b0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
196c0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
196d0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
196e0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
196f0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
19700 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
19710 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
19720 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
19730 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
19740 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
19750 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
19760 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
19770 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
19780 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
19790 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
197a0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
197b0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
197c0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
197d0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
197e0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
197f0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
19800 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
19810 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
19820 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
19830 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
19840 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
19850 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
19860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19870 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19880 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19890 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
198a0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
198b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
198c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
198d0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
198e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
198f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
19900 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
19910 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
19920 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
19930 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
19940 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
19950 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
19960 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
19970 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
19980 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
19990 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
199a0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
199b0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
199c0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
199d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
199e0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
199f0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
19a00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19a10 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
19a20 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
19a30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
19a40 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
19a50 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
19a60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19a70 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
19a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
19a90 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
19aa0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
19ab0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
19ac0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
19ad0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
19ae0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
19af0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
19b00 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
19b10 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
19b20 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
19b30 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
19b40 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
19b50 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
19b60 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
19b70 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
19b80 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
19b90 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
19ba0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
19bb0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
19bc0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
19bd0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
19be0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
19bf0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
19c00 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
19c10 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
19c20 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
19c30 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
19c40 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
19c50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19c60 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
19c70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
19c80 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
19c90 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
19ca0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
19cb0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
19cc0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
19cd0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
19ce0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
19cf0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
19d00 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
19d10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
19d20 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
19d30 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
19d40 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
19d50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
19d60 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
19d70 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
19d80 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
19d90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
19da0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
19db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
19dc0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
19dd0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
19de0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
19df0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
19e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
19e10 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
19e20 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
19e30 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
19e40 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
19e50 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
19e60 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19e70 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
19e80 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
19e90 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
19ea0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
19eb0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
19ec0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19ed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
19ee0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
19ef0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
19f00 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
19f10 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
19f20 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
19f30 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
19f40 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
19f50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19f60 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
19f70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
19f80 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
19f90 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
19fa0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
19fb0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
19fc0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
19fd0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
19fe0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
19ff0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1a000 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a010 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1a020 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1a030 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1a040 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1a050 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1a060 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a070 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1a080 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1a090 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a0a0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1a0b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1a0c0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1a0d0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1a0e0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1a0f0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1a100 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1a110 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1a120 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1a130 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1a140 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1a150 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1a160 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1a170 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1a180 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1a190 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1a1a0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
1a1b0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
1a1c0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1a1d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1f0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
1a200 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
1a210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a220 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
1a230 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
1a240 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1a250 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a270 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
1a280 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
1a290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1a2a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a2b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a2c0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
1a2d0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
1a2e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1a2f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a310 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
1a320 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
1a330 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1a340 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1a360 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
1a370 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
1a380 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1a390 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1a3a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1a3b0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
1a3c0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
1a3d0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1a3e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a400 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
1a410 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
1a420 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1a430 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1a440 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a450 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
1a460 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
1a470 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1a480 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a490 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
1a4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a4b0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1a4c0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1a4d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a4e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
1a4f0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
1a500 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1a510 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1a520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a530 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
1a540 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
1a550 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1a560 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a580 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1a590 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
1a5a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1a5b0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a5c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a5d0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1a5e0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
1a5f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a620 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1a630 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
1a640 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1a650 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1a660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a670 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
1a680 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
1a690 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1a6a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a6b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a6c0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
1a6d0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
1a6e0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1a6f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a710 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
1a720 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
1a730 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1a740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a760 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
1a770 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
1a780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1a790 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a7b0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
1a7c0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
1a7d0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
1a7e0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
1a7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1a800 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
1a810 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
1a820 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1a830 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1a840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
1a850 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
1a860 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
1a870 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1a880 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
1a8a0 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
1a8b0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
1a8c0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
1a8d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a8e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
1a8f0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1a900 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
1a910 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1a920 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1a930 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
1a940 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1a950 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
1a960 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1a970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a980 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
1a990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1a9a0 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
1a9b0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
1a9c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a9d0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
1a9e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
1a9f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1aa00 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
1aa10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1aa20 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
1aa30 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
1aa40 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1aa50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1aa60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aa70 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
1aa80 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
1aa90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1aaa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1aab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1aac0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
1aad0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
1aae0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1aaf0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1ab00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ab10 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
1ab20 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
1ab30 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ab40 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1ab50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ab60 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
1ab70 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
1ab80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ab90 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
1aba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1abb0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
1abc0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
1abd0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1abe0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
1abf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ac00 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
1ac10 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
1ac20 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
1ac30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ac40 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1ac50 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1ac60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1ac70 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1ac80 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ac90 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1aca0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1acb0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1acc0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1acd0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1ace0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1acf0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1ad00 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1ad10 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
1ad20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
1ad30 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
1ad40 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1ad50 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
1ad60 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
1ad70 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
1ad80 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1ad90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1ada0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
1adb0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
1adc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1add0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
1ade0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
1adf0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
1ae00 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
1ae10 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1ae20 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
1ae30 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
1ae40 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
1ae50 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
1ae60 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
1ae70 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
1ae80 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
1ae90 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
1aea0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
1aeb0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
1aec0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1aed0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1aee0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
1aef0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
1af00 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
1af10 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
1af20 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
1af30 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1af40 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
1af50 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
1af60 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
1af70 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
1af80 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
1af90 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
1afa0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
1afb0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1afc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
1afd0 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
1afe0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
1aff0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
1b000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1b010 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
1b020 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
1b030 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
1b040 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
1b050 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
1b060 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
1b070 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
1b080 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1b090 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
1b0a0 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
1b0b0 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
1b0c0 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
1b0d0 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
1b0e0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1b0f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
1b100 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
1b110 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
1b120 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1b130 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
1b140 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
1b150 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1b160 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1b170 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1b180 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1b190 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1b1a0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1b1b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1b1c0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1b1d0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1b1e0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1b1f0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1b200 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1b210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1b220 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1b230 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1b240 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1b250 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1b260 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1b270 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1b280 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1b290 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1b2a0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1b2b0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1b2c0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1b2d0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1b2e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1b2f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1b300 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1b310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b320 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1b330 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1b340 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1b350 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1b360 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1b370 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1b380 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1b390 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1b3a0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1b3b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1b3c0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1b3d0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1b3e0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1b3f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
1b400 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1b410 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1b420 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1b430 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1b440 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1b450 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1b460 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
1b470 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1b480 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1b490 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1b4a0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1b4b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b4c0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1b4d0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1b4e0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1b4f0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1b500 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1b510 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1b520 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1b530 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1b540 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1b550 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1b560 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1b570 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1b580 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1b590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1b5a0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1b5b0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b5c0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1b5d0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1b5e0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1b5f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1b600 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1b610 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1b620 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1b630 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1b640 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1b650 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1b660 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1b670 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1b680 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1b690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b6a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1b6b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1b6c0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1b6d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b6e0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1b6f0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1b700 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1b710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b720 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1b730 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1b740 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1b750 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
1b760 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1b770 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1b780 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1b790 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1b7a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b7b0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1b7c0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1b7d0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1b7e0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1b7f0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1b800 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
1b810 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
1b820 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1b830 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1b840 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1b850 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1b860 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1b870 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1b880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b890 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1b8a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1b8b0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1b8c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1b8d0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1b8e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1b8f0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1b900 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1b910 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1b920 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1b930 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1b940 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1b950 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1b960 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1b970 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1b980 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1b990 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1b9a0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1b9b0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1b9c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1b9d0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1b9e0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1b9f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ba00 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1ba10 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1ba20 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1ba30 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1ba40 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1ba50 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1ba60 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1ba70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1ba80 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1ba90 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1baa0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1bab0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1bac0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1bad0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1bae0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1baf0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1bb00 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1bb10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1bb20 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1bb30 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1bb40 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1bb50 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1bb60 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1bb70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1bb80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1bb90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1bba0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1bbb0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1bbc0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1bbd0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1bbe0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1bbf0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1bc00 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1bc10 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1bc20 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1bc30 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1bc40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1bc50 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1bc60 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1bc70 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1bc80 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1bc90 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1bca0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1bcb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1bcc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1bcd0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1bce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1bcf0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1bd00 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1bd10 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1bd20 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1bd30 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1bd40 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1bd50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1bd60 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1bd70 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1bd80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1bd90 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1bda0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1bdb0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1bdc0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1bdd0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1bde0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1bdf0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1be00 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1be10 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1be20 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f  DCACHE],.** and/
1be30 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1be40 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1be50 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1be60 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1be70 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1be80 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1be90 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1bea0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1beb0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1bec0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1bed0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1bee0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1bef0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1bf00 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1bf10 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1bf20 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1bf30 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1bf40 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1bf50 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1bf60 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1bf70 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1bf80 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1bf90 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1bfa0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1bfb0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1bfc0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1bfd0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1bfe0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1bff0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1c000 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1c010 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1c020 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c030 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1c040 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1c050 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1c060 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1c070 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1c080 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1c090 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
1c0a0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1c0b0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1c0c0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1c0d0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1c0e0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1c0f0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1c100 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1c110 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1c120 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1c130 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1c140 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1c150 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1c160 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1c170 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1c180 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1c190 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1c1a0 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1c1b0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1c1c0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1c1d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1c1e0 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
1c1f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1c200 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
1c210 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1c220 45 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  ECACHE] flags,.*
1c230 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1c240 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1c250 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c260 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1c270 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1c280 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1c290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1c2a0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1c2b0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1c2c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1c2d0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1c2e0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1c2f0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1c300 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1c310 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1c320 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1c330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1c340 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1c350 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1c360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c370 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1c380 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1c390 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1c3a0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1c3b0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1c3c0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1c3d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1c3e0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1c3f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1c400 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1c410 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1c420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c430 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1c440 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1c450 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1c460 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1c470 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1c480 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1c490 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1c4a0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1c4b0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1c4c0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1c4d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1c4e0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1c4f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c500 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1c510 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1c520 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1c530 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1c540 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1c550 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1c560 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1c570 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1c580 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1c590 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1c5a0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1c5b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1c5c0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1c5d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1c5e0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1c5f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c600 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1c610 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1c620 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1c630 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1c640 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1c650 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1c660 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1c670 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1c680 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1c690 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1c6a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1c6b0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1c6c0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1c6d0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1c6e0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1c6f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1c700 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1c710 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1c720 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1c730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c740 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1c750 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1c760 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1c770 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1c780 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1c790 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1c7a0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1c7b0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1c7c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1c7d0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1c7e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c7f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1c800 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1c810 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1c820 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1c830 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1c840 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1c850 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1c860 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1c870 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1c880 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1c890 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1c8a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1c8b0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1c8c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1c8d0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1c8e0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1c8f0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1c900 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1c910 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1c920 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1c930 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1c940 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1c950 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1c960 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1c970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1c980 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1c990 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1c9a0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1c9b0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1c9c0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1c9d0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1c9e0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1c9f0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1ca00 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1ca10 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1ca20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1ca30 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1ca40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1ca50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ca60 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1ca70 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1ca80 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1ca90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1caa0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1cab0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1cac0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1cad0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1cae0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1caf0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1cb00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1cb10 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1cb20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1cb30 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1cb40 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1cb50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1cb60 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1cb70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1cb80 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1cb90 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1cba0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1cbb0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1cbc0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1cbd0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1cbe0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1cbf0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1cc00 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1cc10 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1cc20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1cc30 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1cc40 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1cc50 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1cc60 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1cc70 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1cc80 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1cc90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1cca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1ccb0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1ccc0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1ccd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1cce0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1ccf0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1cd00 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1cd10 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1cd20 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1cd30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cd40 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1cd50 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1cd60 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1cd70 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1cd80 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1cd90 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1cda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1cdb0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1cdc0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1cdd0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1cde0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1cdf0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1ce00 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1ce10 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1ce20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1ce30 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1ce40 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1ce50 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1ce60 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1ce70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1ce80 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1ce90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1cea0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ceb0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1cec0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ced0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1cee0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1cef0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1cf00 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1cf10 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1cf20 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1cf30 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1cf40 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1cf50 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1cf60 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1cf70 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1cf80 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1cf90 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1cfa0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1cfb0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1cfc0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1cfd0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1cfe0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1cff0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1d000 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1d010 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1d020 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d030 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1d040 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1d050 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1d060 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1d070 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1d080 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1d090 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1d0a0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1d0b0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1d0c0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1d0d0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1d0e0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1d0f0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1d100 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1d110 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1d120 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1d130 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1d140 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1d150 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1d160 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1d170 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1d180 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1d190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1d1a0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1d1b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1d1c0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1d1d0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1d1e0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1d1f0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1d200 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1d210 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1d220 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1d230 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1d240 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1d250 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1d260 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1d270 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1d280 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1d290 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1d2a0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1d2b0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1d2c0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1d2d0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1d2e0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1d2f0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1d300 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1d310 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1d320 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1d330 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1d340 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1d350 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1d360 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1d370 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1d380 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1d390 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1d3a0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1d3b0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1d3c0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1d3d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1d3e0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1d3f0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1d400 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1d410 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1d420 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1d430 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1d440 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1d450 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1d460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1d470 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1d480 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1d490 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1d4a0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1d4b0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1d4c0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1d4d0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1d4e0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1d4f0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1d500 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1d510 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1d520 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1d530 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1d540 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1d550 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d560 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1d570 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1d580 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1d590 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1d5a0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1d5b0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1d5c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1d5d0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1d5e0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1d5f0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1d600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d610 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1d620 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1d630 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1d640 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1d650 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1d660 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1d670 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1d680 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1d690 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1d6a0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1d6b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1d6c0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1d6d0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1d6e0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1d6f0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1d700 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1d710 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1d720 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1d730 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1d740 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1d750 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1d760 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1d770 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1d780 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1d790 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1d7a0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1d7b0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1d7c0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1d7d0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1d7e0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1d7f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d800 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1d810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d820 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1d830 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1d840 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1d850 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d860 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1d870 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1d880 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1d890 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1d8a0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1d8b0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1d8c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1d8d0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1d8e0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1d8f0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
1d900 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
1d910 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
1d920 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
1d930 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
1d940 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
1d950 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
1d960 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
1d970 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
1d980 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
1d990 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
1d9a0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
1d9b0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
1d9c0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1d9d0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
1d9e0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
1d9f0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
1da00 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
1da10 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
1da20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
1da30 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
1da40 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1da50 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1da60 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1da70 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1da80 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1da90 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
1daa0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
1dab0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1dac0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
1dad0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
1dae0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
1daf0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
1db00 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1db10 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
1db20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
1db30 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
1db40 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1db50 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
1db60 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
1db70 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
1db80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1db90 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
1dba0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
1dbb0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
1dbc0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1dbd0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1dbe0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1dbf0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1dc00 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1dc10 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1dc20 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1dc30 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1dc40 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1dc50 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1dc60 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1dc70 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1dc80 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1dc90 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
1dca0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
1dcb0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
1dcc0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
1dcd0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
1dce0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
1dcf0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
1dd00 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
1dd10 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
1dd20 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
1dd30 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
1dd40 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
1dd50 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
1dd60 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
1dd70 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
1dd80 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
1dd90 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
1dda0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
1ddb0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
1ddc0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
1ddd0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
1dde0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
1ddf0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
1de00 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
1de10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1de20 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
1de30 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
1de40 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
1de50 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
1de60 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
1de70 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
1de80 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
1de90 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
1dea0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
1deb0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
1dec0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
1ded0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
1dee0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
1def0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
1df00 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1df10 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
1df20 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1df30 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1df40 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1df50 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1df60 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1df70 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
1df80 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
1df90 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
1dfa0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1dfb0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1dfc0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
1dfd0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
1dfe0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
1dff0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
1e000 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e010 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
1e020 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
1e030 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
1e040 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
1e050 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
1e060 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
1e070 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
1e080 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
1e090 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
1e0a0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
1e0b0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  >.** ^(<dt>SQLIT
1e0c0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1e0d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e0e0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1e0f0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
1e100 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
1e110 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
1e120 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e130 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1e140 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1e150 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1e160 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
1e170 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
1e180 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e190 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e1a0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
1e1b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e1c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1e1d0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
1e1e0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
1e1f0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
1e200 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
1e210 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1e220 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1e230 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1e240 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1e250 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1e260 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
1e270 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1e280 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
1e290 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e2a0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
1e2b0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
1e2c0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
1e2d0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
1e2e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e2f0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1e300 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
1e310 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e320 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
1e330 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
1e340 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
1e350 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1e360 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
1e370 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
1e380 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e390 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
1e3a0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
1e3b0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
1e3c0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
1e3d0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
1e3e0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
1e3f0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
1e400 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
1e410 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
1e420 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
1e430 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
1e440 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
1e450 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1e460 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e470 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
1e480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e490 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1e4a0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
1e4b0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
1e4c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1e4d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1e4e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e4f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e500 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
1e510 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
1e520 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e  .)^</dd>.**.** ^
1e530 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e540 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1e550 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e560 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1e570 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1e580 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1e590 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
1e5a0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1e5b0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1e5c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e5d0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1e5e0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1e5f0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
1e600 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
1e610 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
1e620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
1e630 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1e640 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1e650 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1e660 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e670 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1e680 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1e6a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1e6b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1e6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e6d0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1e6e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1e6f0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1e700 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1e710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1e720 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1e730 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1e740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1e750 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1e760 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1e770 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1e780 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1e790 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1e7a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1e7b0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1e7c0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1e7d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e7e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1e7f0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1e800 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e810 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1e820 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1e830 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e840 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1e850 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1e860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e870 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1e880 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1e890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e8a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1e8b0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1e8c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e8d0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1e8e0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1e8f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1e900 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1e910 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1e920 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1e930 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1e940 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1e950 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1e960 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1e970 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1e980 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1e990 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1e9a0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1e9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1e9c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1e9d0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1e9e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1e9f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1ea00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1ea10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1ea20 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1ea30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ea40 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1ea50 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1ea60 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1ea70 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1ea80 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1ea90 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1eaa0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1eab0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1eac0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1ead0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1eae0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1eaf0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1eb00 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1eb10 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1eb20 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1eb30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1eb40 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1eb50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1eb60 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1eb70 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1eb80 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1eb90 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1eba0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1ebb0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1ebc0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1ebd0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1ebe0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1ebf0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1ec00 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1ec10 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1ec20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1ec30 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1ec40 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1ec50 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1ec60 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1ec70 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1ec80 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1ec90 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1eca0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1ecb0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1ecc0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1ecd0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1ece0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1ecf0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1ed00 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1ed10 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1ed20 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1ed30 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1ed40 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1ed50 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1ed60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1ed70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1ed80 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1ed90 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1eda0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1edb0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1edc0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1edd0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1ede0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1edf0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1ee00 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1ee10 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1ee20 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1ee30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1ee40 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1ee50 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1ee60 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1ee70 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1ee80 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1ee90 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1eea0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1eeb0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1eec0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1eed0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1eee0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1eef0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1ef00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1ef10 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1ef20 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1ef30 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1ef40 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1ef50 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1ef60 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1ef70 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1ef80 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1ef90 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1efa0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1efb0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1efc0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1efd0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1efe0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1eff0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1f000 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1f010 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1f020 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1f030 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1f040 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1f050 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1f060 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1f070 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1f080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1f090 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1f0a0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1f0b0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1f0c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1f0d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1f0e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1f0f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1f110 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1f120 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1f130 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1f140 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1f150 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1f160 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1f170 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1f180 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f190 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1f1a0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1f1b0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1f1c0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1f1d0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1f1e0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1f1f0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1f200 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1f210 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1f220 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1f230 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1f240 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1f250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1f260 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1f270 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1f280 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1f290 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1f2a0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1f2b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1f2c0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1f2d0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1f2e0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1f2f0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1f300 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1f310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f320 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1f330 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1f340 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1f350 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1f360 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f   it again..** </
1f370 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1f380 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
1f390 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
1f3a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
1f3b0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
1f3c0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
1f3d0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
1f3e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
1f3f0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
1f400 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
1f410 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
1f420 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
1f430 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
1f440 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
1f450 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
1f460 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
1f470 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
1f480 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
1f490 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
1f4a0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
1f4b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
1f4c0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1f4d0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
1f4e0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
1f4f0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
1f500 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
1f510 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
1f520 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
1f530 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1f540 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
1f550 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
1f560 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
1f570 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
1f580 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
1f590 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1f5a0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
1f5b0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
1f5c0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
1f5d0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
1f5e0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
1f5f0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
1f600 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
1f610 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1f620 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
1f630 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
1f640 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
1f650 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
1f660 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
1f670 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
1f680 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
1f690 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1f6a0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
1f6b0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
1f6c0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
1f6d0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
1f6e0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
1f6f0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
1f700 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
1f710 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
1f720 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
1f730 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1f740 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
1f750 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
1f760 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1f770 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
1f780 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
1f790 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
1f7a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
1f7b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
1f7c0 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT2] compile-t
1f7d0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
1f7e0 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a  abled..** the .*
1f7f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1f800 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f810 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1f820 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f830 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1f840 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f850 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1f860 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1f870 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1f880 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1f890 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1f8a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1f8b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1f8c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1f8d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1f8e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1f8f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1f900 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1f910 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1f920 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1f930 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1f940 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1f950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1f960 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f970 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f980 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f9a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f9b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1f9c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f9d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f9e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f9f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1fa00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1fa10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1fa20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1fa30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1fa40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1fa50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1fa60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1fa70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1fa80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1fa90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1faa0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1fab0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1fac0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1fad0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1fae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1faf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1fb00 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1fb10 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1fb20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1fb30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1fb40 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1fb50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1fb60 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1fb70 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1fb80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1fb90 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1fba0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1fbb0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1fbc0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1fbd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1fbe0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1fbf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1fc00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1fc10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1fc20 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1fc30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1fc40 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1fc50 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1fc60 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1fc70 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1fc80 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1fc90 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1fca0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1fcb0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1fcc0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1fcd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1fce0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1fcf0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1fd00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1fd10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1fd20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
1fd30 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1fd40 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
1fd50 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1fd60 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1fd70 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1fd80 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1fd90 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1fda0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1fdb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fdc0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1fdd0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1fde0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1fdf0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1fe00 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1fe10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1fe20 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
1fe30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1fe40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1fe50 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1fe60 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1fe70 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1fe80 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
1fe90 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
1fea0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
1feb0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
1fec0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1fed0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
1fee0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
1fef0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1ff00 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
1ff10 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
1ff20 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
1ff30 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
1ff40 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
1ff50 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
1ff60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1ff70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1ff80 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
1ff90 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
1ffa0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
1ffb0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
1ffc0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
1ffd0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
1ffe0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
1fff0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
20000 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
20010 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
20020 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
20030 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
20040 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
20050 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
20060 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
20070 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
20080 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
20090 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
200a0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
200b0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
200c0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
200d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
200e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
200f0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
20100 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
20110 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
20120 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
20130 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
20140 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
20150 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
20160 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
20170 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
20180 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
20190 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
201a0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
201b0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
201c0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
201d0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
201e0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
201f0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
20200 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
20210 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
20220 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
20230 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
20240 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
20250 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
20260 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
20270 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
20280 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
20290 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
202a0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
202b0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
202c0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
202d0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
202e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
202f0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
20300 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
20310 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
20320 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
20330 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
20340 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
20350 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
20360 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
20370 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
20380 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
20390 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
203a0 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
203b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
203c0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
203d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
203e0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
203f0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
20400 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
20410 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
20420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
20430 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
20440 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
20450 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
20460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20470 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
20480 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
20490 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
204a0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
204b0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
204c0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
204d0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
204e0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
204f0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
20500 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
20510 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
20520 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
20530 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
20540 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
20550 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
20560 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
20570 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
20580 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
20590 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
205a0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
205b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
205c0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
205d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
205e0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
205f0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
20600 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
20610 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
20620 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20630 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
20640 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
20650 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
20660 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
20670 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
20680 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
20690 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
206a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
206b0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
206c0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
206d0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
206e0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
206f0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
20700 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
20710 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
20720 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
20730 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20740 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
20750 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
20760 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
20770 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20780 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
20790 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
207a0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
207b0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
207c0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
207d0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
207e0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
207f0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
20800 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
20810 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
20820 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
20830 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
20840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
20850 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
20860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
20870 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
20880 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
20890 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
208a0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
208b0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
208c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
208d0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
208e0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
208f0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
20900 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
20910 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
20920 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
20930 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
20940 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
20950 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
20960 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
20970 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
20980 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20990 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
209a0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
209b0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
209c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
209d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
209e0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
209f0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
20a00 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
20a10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
20a20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
20a30 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
20a40 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
20a50 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
20a60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
20a70 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
20a80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
20a90 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
20aa0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
20ab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20ac0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
20ad0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
20ae0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
20af0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
20b00 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
20b10 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
20b20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
20b30 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
20b40 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
20b50 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
20b60 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
20b70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20b80 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
20b90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
20ba0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
20bb0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
20bc0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
20bd0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
20be0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
20bf0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
20c00 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
20c10 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
20c20 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
20c30 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
20c40 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
20c50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20c60 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
20c70 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
20c80 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
20c90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20ca0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
20cb0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
20cc0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
20cd0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
20ce0 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
20cf0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
20d00 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
20d10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
20d20 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
20d30 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
20d40 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
20d50 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
20d60 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
20d70 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
20d80 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
20d90 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
20da0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
20db0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
20dc0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
20dd0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
20de0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
20df0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
20e00 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
20e10 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
20e20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
20e30 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
20e40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
20e50 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
20e60 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
20e70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
20e80 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
20e90 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
20ea0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
20eb0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
20ec0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
20ed0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20ee0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
20ef0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f00 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
20f10 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
20f20 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
20f30 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
20f40 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
20f50 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
20f60 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
20f70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
20f80 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
20f90 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
20fa0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
20fb0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
20fc0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
20fd0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
20fe0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
20ff0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
21000 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
21010 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
21020 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
21030 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
21040 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
21050 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
21060 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
21070 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
21080 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
21090 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
210a0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
210b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
210c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
210d0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
210e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
210f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
21100 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
21110 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
21120 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
21130 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
21140 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
21150 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
21160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21170 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
21180 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
21190 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
211a0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
211b0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
211c0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
211d0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
211e0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
211f0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
21200 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
21210 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
21220 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
21230 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
21240 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
21250 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
21260 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
21270 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
21280 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
21290 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
212a0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
212b0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
212c0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
212d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
212e0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
212f0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
21300 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
21310 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
21320 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
21330 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
21340 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
21350 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
21360 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
21370 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
21380 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
21390 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
213a0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
213b0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
213c0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
213d0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
213e0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
213f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
21400 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
21410 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
21420 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
21430 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
21440 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
21450 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
21460 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
21470 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
21480 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
21490 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
214a0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
214b0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
214c0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
214d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
214e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
214f0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
21500 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
21510 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
21520 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
21530 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
21540 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
21550 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
21560 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
21570 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
21580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21590 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
215a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
215b0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
215c0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
215d0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
215e0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
215f0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
21600 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
21610 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
21620 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
21630 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
21640 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
21650 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
21660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21670 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
21680 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
21690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
216a0 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
216b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
216c0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
216d0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
216e0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
216f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
21700 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
21710 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
21720 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
21730 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
21740 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
21750 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
21760 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
21770 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
21780 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
21790 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
217a0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
217b0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
217c0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
217d0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
217e0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
217f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
21800 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
21810 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
21820 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
21830 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
21840 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
21850 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
21860 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
21870 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
21880 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
21890 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
218a0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
218b0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
218c0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
218d0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
218e0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
218f0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
21900 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
21910 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
21920 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
21930 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
21940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
21950 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
21960 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
21970 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
21980 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
21990 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
219a0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
219b0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
219c0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
219d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
219e0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
219f0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
21a00 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
21a10 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
21a20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
21a30 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
21a40 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
21a50 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
21a60 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
21a70 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
21a80 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
21a90 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
21aa0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
21ab0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
21ac0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
21ad0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
21ae0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
21af0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
21b00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21b10 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
21b20 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
21b30 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
21b40 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
21b50 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
21b60 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
21b70 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
21b80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21b90 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
21ba0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
21bb0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21bc0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
21bd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
21be0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
21bf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
21c00 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
21c10 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
21c20 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
21c30 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
21c40 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
21c50 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
21c60 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
21c70 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
21c80 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
21c90 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
21ca0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
21cb0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
21cc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21cd0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21ce0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21cf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21d00 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
21d10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21d20 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21d30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
21d40 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
21d50 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
21d60 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
21d70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
21d80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21d90 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
21da0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
21db0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
21dc0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
21dd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
21de0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
21df0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
21e00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
21e10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
21e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21e30 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
21e40 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
21e50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21e60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21e70 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
21e80 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
21e90 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
21ea0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21eb0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21ec0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
21ed0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
21ee0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
21ef0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
21f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21f10 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
21f20 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
21f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
21f40 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
21f50 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
21f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21f70 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
21f80 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
21f90 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
21fa0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
21fb0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
21fc0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
21fd0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
21fe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21ff0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
22000 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
22010 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
22020 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
22030 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
22040 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
22050 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
22060 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
22070 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
22080 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
22090 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
220a0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
220b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
220c0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
220d0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
220e0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
220f0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
22100 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
22110 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
22120 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
22130 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
22140 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
22150 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
22160 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
22170 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
22180 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
22190 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
221a0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
221b0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
221c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
221d0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
221e0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
221f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22200 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
22210 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22220 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22230 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
22240 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22250 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
22260 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
22270 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
22280 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
22290 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
222a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
222b0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
222c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
222d0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
222e0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
222f0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
22300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22310 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
22320 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
22330 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
22340 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
22350 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
22360 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
22370 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
22380 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
22390 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
223a0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
223b0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
223c0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
223d0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
223e0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
223f0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
22400 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
22410 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
22420 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
22430 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
22440 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
22450 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
22460 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
22470 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
22480 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
22490 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
224a0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
224b0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
224c0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
224d0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
224e0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
224f0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
22500 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
22510 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
22520 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
22530 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
22540 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
22550 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
22560 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
22570 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
22580 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
22590 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
225a0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
225b0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
225c0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
225d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
225e0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
225f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
22600 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
22610 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
22620 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22630 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
22640 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
22650 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22660 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
22670 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22680 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22690 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
226a0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
226b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
226c0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
226d0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
226e0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
226f0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
22700 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
22710 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
22720 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
22730 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
22740 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
22750 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
22760 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
22770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22780 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
22790 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
227a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
227b0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
227c0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
227d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
227e0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
227f0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
22800 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
22810 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
22820 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
22830 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
22840 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
22850 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
22860 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22880 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22890 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
228a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
228b0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
228c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
228d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
228e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
228f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22900 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
22910 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
22920 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
22930 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
22940 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
22950 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
22960 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
22970 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
22980 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
22990 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
229a0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
229b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
229c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
229d0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
229e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
229f0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
22a00 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
22a10 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
22a20 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
22a30 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
22a40 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
22a50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
22a60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
22a70 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
22a80 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
22a90 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
22aa0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
22ab0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
22ac0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
22ad0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
22ae0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
22af0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22b00 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
22b10 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
22b20 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
22b30 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
22b40 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
22b50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
22b60 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22b70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
22b80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
22b90 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
22ba0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
22bb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22bc0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
22bd0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
22be0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
22bf0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
22c00 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
22c10 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
22c20 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
22c30 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
22c40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
22c50 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
22c60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
22c70 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
22c80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
22c90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
22ca0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
22cb0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
22cc0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
22cd0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
22ce0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
22cf0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
22d00 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
22d10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
22d20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22d30 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
22d40 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
22d50 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
22d60 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
22d70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22d80 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
22d90 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
22da0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
22db0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
22dc0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
22dd0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
22de0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
22df0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22e00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
22e10 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
22e20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22e30 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
22e40 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
22e50 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
22e60 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
22e70 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
22e80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
22e90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
22ea0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
22eb0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
22ec0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
22ed0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
22ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22ef0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
22f00 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
22f10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
22f20 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
22f30 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
22f40 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
22f50 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
22f60 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
22f70 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
22f80 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
22f90 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
22fa0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22fb0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
22fc0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
22fd0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
22fe0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
22ff0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
23000 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
23010 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
23020 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
23030 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
23040 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23050 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
23060 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
23070 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
23080 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
23090 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
230a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
230b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
230c0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
230d0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
230e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
230f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
23100 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23110 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
23120 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
23130 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
23140 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
23150 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
23160 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
23170 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
23180 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
23190 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
231a0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
231b0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
231c0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
231d0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
231e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
231f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
23200 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
23210 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
23220 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
23230 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
23240 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
23250 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
23260 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
23270 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
23280 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
23290 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
232a0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
232b0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
232c0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
232d0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
232e0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
232f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
23300 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
23310 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
23320 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
23330 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
23340 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23350 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
23360 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
23370 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
23380 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
23390 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
233a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
233b0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
233c0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
233d0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
233e0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
233f0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
23400 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
23410 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
23420 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
23430 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
23440 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
23450 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
23460 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
23470 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
23480 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
23490 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
234a0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
234b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
234c0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
234d0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
234e0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
234f0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
23500 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
23510 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
23520 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
23530 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
23540 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
23550 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
23560 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
23570 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
23580 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
23590 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
235a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
235b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
235c0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
235d0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
235e0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
235f0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
23600 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
23610 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
23620 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
23630 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
23640 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
23650 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
23660 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
23670 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
23680 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
23690 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
236a0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
236b0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
236c0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
236d0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
236e0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
236f0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
23700 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
23710 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
23720 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
23730 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
23740 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
23750 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
23760 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
23770 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
23780 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
23790 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
237a0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
237b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
237c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
237d0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
237e0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
237f0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
23800 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
23810 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
23820 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
23830 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
23840 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
23850 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23860 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
23870 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
23880 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
23890 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
238a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
238b0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
238c0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
238d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
238e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
238f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
23900 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
23910 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
23920 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23930 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
23940 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
23950 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
23960 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
23970 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
23980 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23990 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
239a0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
239b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
239c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
239d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
239e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
239f0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
23a00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
23a10 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
23a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23a30 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
23a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23a50 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
23a60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23a70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
23a90 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
23aa0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
23ab0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23ac0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
23ad0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
23ae0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
23af0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
23b00 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
23b10 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
23b20 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
23b30 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
23b40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23b50 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
23b60 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
23b70 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
23b80 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
23b90 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
23ba0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
23bb0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
23bc0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
23bd0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
23be0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
23bf0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
23c00 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
23c10 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
23c20 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
23c30 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
23c40 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
23c50 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
23c60 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
23c70 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
23c80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23c90 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
23ca0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
23cb0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
23cc0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
23cd0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
23ce0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
23cf0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
23d00 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
23d10 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
23d20 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
23d30 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
23d40 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
23d50 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
23d60 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
23d70 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
23d80 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
23d90 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
23da0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
23db0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
23dc0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
23dd0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
23de0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
23df0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
23e00 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
23e10 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
23e20 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
23e30 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
23e40 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
23e50 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
23e60 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
23e70 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
23e80 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
23e90 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
23ea0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
23eb0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
23ec0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
23ed0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
23ee0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
23ef0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
23f00 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
23f10 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
23f20 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
23f30 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
23f40 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
23f50 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
23f60 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
23f70 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
23f80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
23f90 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
23fa0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23fb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
23fd0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
23fe0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
23ff0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
24000 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
24010 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
24020 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24030 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
24040 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
24050 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
24060 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24070 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
24080 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
24090 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
240a0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
240b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
240c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
240d0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
240e0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
240f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
24100 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
24110 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
24120 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
24130 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
24140 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
24150 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
24160 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
24170 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
24180 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
24190 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
241a0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
241b0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
241c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
241d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
241e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
241f0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
24200 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
24210 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
24220 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
24230 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
24240 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
24250 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
24260 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
24270 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
24280 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
24290 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
242a0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
242b0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
242c0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
242d0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
242e0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
242f0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
24300 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
24310 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
24320 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
24330 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
24340 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
24350 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
24360 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
24370 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
24380 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
24390 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
243a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
243b0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
243c0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
243d0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
243e0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
243f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
24400 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
24410 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
24420 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
24430 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
24440 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
24450 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
24460 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
24470 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
24480 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
24490 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
244a0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
244b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
244c0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
244d0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
244e0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
244f0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
24500 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
24510 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
24520 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
24530 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
24540 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
24550 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
24560 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
24570 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
24580 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
24590 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
245a0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
245b0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
245c0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
245d0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
245e0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
245f0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
24600 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24610 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
24620 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
24630 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
24640 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
24650 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
24660 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
24670 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
24680 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
24690 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
246a0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
246b0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
246c0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
246d0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
246e0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
246f0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
24700 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
24710 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
24720 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
24730 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
24740 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
24750 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
24760 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
24770 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
24780 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
24790 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
247a0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
247b0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
247c0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
247d0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
247e0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
247f0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
24800 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
24810 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
24820 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
24830 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
24840 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
24850 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
24860 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
24870 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
24880 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
24890 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
248a0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
248b0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
248c0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
248d0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
248e0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
248f0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
24900 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24910 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
24920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
24930 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
24940 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
24950 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
24960 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
24970 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
24980 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
24990 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
249a0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
249b0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
249c0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
249d0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
249e0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
249f0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
24a00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24a10 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
24a20 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
24a30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
24a40 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
24a50 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
24a60 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
24a70 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
24a80 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
24a90 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
24aa0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
24ab0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
24ac0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24ad0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
24ae0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
24af0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
24b00 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
24b10 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
24b20 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
24b30 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
24b40 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
24b50 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
24b60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
24b70 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
24b80 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
24b90 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
24ba0 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
24bb0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
24bc0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
24bd0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
24be0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
24bf0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
24c00 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
24c10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
24c20 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
24c30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24c40 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
24c50 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
24c60 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
24c70 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
24c80 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
24c90 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
24ca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
24cb0 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
24cc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24cd0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
24ce0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
24cf0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
24d00 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
24d10 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
24d20 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
24d30 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
24d40 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
24d50 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
24d60 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
24d70 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
24d80 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
24d90 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
24da0 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
24db0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
24dc0 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
24dd0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
24de0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24df0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
24e00 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
24e10 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
24e20 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
24e30 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
24e40 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
24e50 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
24e60 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
24e70 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
24e80 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
24e90 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
24ea0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
24eb0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
24ec0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
24ed0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
24ee0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
24ef0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24f00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
24f10 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
24f20 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
24f30 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
24f40 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
24f50 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
24f60 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
24f70 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
24f80 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
24f90 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
24fa0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
24fb0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
24fc0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24fd0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
24fe0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
24ff0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
25000 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
25010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25020 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25030 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
25040 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
25050 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
25060 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
25070 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25080 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
25090 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
250a0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
250b0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
250c0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
250d0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
250e0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
250f0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
25100 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
25110 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
25120 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
25130 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
25140 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
25150 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25160 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
25170 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25180 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
25190 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
251a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
251b0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
251c0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
251d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
251e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
251f0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
25200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25210 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
25220 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
25230 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
25240 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
25250 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25260 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
25270 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
25280 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
25290 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
252a0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
252b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
252c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
252d0 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
252e0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
252f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
25300 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
25320 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
25330 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
25340 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
25350 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25360 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
25370 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
25380 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
25390 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
253a0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
253b0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
253c0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
253d0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
253e0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
253f0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
25400 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
25410 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
25420 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
25430 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
25440 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
25450 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
25460 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
25470 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
25480 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
25490 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
254a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
254b0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
254c0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
254d0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
254e0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
254f0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
25500 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
25510 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
25520 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
25530 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
25540 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
25550 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
25560 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
25570 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
25580 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
25590 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
255a0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
255b0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
255c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
255d0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
255e0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
255f0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
25600 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
25610 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
25620 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
25630 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
25640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
25650 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
25660 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
25670 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
25680 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
25690 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
256a0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
256b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
256c0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
256d0 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
256e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
256f0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
25700 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
25710 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
25720 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
25730 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
25740 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
25750 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
25760 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
25770 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
25780 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
25790 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
257a0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
257b0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
257c0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
257d0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
257e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
257f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
25800 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
25810 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
25820 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
25830 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
25840 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
25850 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
25860 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
25870 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
25880 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
25890 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
258a0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
258b0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
258c0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
258d0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
258e0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
258f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25900 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
25910 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
25920 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
25930 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
25940 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
25950 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
25960 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
25970 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
25980 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
25990 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
259a0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
259b0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
259c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
259d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
259e0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
259f0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
25a00 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
25a10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25a20 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
25a30 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
25a40 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
25a50 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
25a60 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
25a70 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
25a80 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
25a90 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
25aa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
25ab0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
25ac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
25ad0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
25ae0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
25af0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
25b00 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
25b10 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
25b20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
25b30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25b40 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
25b50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25b60 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
25b70 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
25b80 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
25b90 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
25ba0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
25bb0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
25bc0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
25bd0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
25bf0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
25c00 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
25c10 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
25c20 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
25c30 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
25c40 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
25c50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
25c60 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
25c70 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
25c80 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
25c90 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
25ca0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
25cb0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
25cc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
25cd0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
25ce0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
25cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
25d00 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
25d10 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
25d20 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
25d30 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
25d40 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
25d50 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
25d60 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
25d70 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
25d80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25d90 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
25da0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
25db0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
25dc0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
25dd0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
25de0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
25df0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
25e00 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
25e10 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
25e20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
25e30 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
25e40 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
25e50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25e60 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
25e70 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
25e80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
25e90 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
25ea0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
25eb0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
25ec0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
25ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25ee0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
25ef0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
25f00 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
25f10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
25f20 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
25f30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25f40 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
25f50 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
25f60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
25f70 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
25f80 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
25f90 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
25fa0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
25fb0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
25fc0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
25fd0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
25fe0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
25ff0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
26000 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
26010 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
26020 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
26030 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
26040 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
26050 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
26060 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
26070 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
26080 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
26090 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
260a0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
260b0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
260c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
260d0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
260e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
260f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
26100 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
26110 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
26120 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
26130 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
26140 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
26150 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
26160 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
26170 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26180 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
26190 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
261a0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
261b0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
261c0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
261d0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
261e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
261f0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
26200 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
26210 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
26220 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
26230 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
26240 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
26250 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
26260 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
26270 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
26280 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
26290 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
262a0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
262b0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
262c0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
262d0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
262e0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
262f0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
26300 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
26310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26320 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
26330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26340 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
26350 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
26360 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
26370 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
26380 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
26390 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
263a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
263b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
263c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
263d0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
263e0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
263f0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
26400 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
26410 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
26420 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
26430 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
26440 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
26450 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
26460 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
26470 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
26480 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
26490 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
264a0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
264b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
264c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
264d0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
264e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
264f0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
26500 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
26510 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
26520 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26530 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
26540 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
26550 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26560 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
26570 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
26580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
26590 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
265a0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
265b0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
265c0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
265d0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
265e0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
265f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
26600 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
26610 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
26620 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
26630 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
26640 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
26650 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
26660 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
26670 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
26680 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
26690 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
266a0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
266b0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
266c0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
266d0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
266e0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
266f0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
26700 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
26710 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
26720 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
26730 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
26740 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
26750 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
26760 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
26770 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
26780 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
26790 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
267a0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
267b0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
267c0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
267d0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
267e0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
267f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
26800 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
26810 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
26820 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
26830 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
26840 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
26850 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
26860 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
26870 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
26880 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
26890 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
268a0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
268b0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
268c0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
268d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
268e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
268f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
26900 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
26910 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
26920 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
26930 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
26940 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
26950 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
26960 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
26970 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
26980 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
26990 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
269a0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
269b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
269c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
269d0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
269e0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
269f0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
26a00 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
26a10 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
26a20 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
26a30 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
26a40 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
26a50 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
26a60 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
26a70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
26a80 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
26a90 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
26aa0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
26ab0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
26ac0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
26ad0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
26ae0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
26af0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
26b00 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
26b10 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
26b20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
26b30 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
26b40 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
26b50 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
26b60 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
26b70 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
26b80 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
26b90 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
26ba0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
26bb0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
26bc0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
26bd0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
26be0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
26bf0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
26c00 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
26c10 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
26c20 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
26c30 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
26c40 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
26c50 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
26c60 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
26c70 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
26c80 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
26c90 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
26ca0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
26cb0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
26cc0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
26cd0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
26ce0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
26cf0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
26d00 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
26d10 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
26d20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
26d30 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
26d40 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
26d50 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
26d60 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
26d70 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
26d80 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
26d90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
26da0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
26db0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
26dc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
26dd0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
26de0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
26df0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
26e00 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
26e10 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
26e20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
26e30 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
26e40 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
26e50 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
26e60 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
26e70 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
26e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
26e90 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
26ea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26eb0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
26ec0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
26ed0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
26ee0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
26ef0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
26f00 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
26f10 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
26f20 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
26f30 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
26f40 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
26f50 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
26f60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
26f70 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
26f80 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
26f90 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
26fa0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
26fb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
26fc0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
26fd0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
26fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26ff0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
27000 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
27010 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
27020 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
27030 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
27040 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
27050 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
27060 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
27070 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
27080 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
27090 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
270a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
270b0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
270c0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
270d0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
270e0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
270f0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
27100 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
27110 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
27120 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
27130 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
27140 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
27150 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
27160 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
27170 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
27180 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
27190 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
271a0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
271b0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
271c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
271d0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
271e0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
271f0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
27200 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
27210 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
27220 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
27230 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
27240 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
27250 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
27260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27270 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
27280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27290 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
272a0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
272b0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
272c0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
272d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
272e0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
272f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
27300 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
27310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27320 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
27330 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
27340 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
27350 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
27360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27370 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
27380 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
27390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
273a0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
273b0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
273c0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
273d0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
273e0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
273f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
27400 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
27410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
27420 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
27430 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
27440 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
27450 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
27460 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
27470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27480 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
27490 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
274a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
274b0 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
274c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
274d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
274e0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
274f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
27500 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
27510 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
27520 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
27530 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
27540 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
27550 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
27560 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
27570 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27580 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
27590 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
275a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
275b0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
275c0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
275d0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
275e0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
275f0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
27600 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
27610 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
27620 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
27630 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
27640 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
27650 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27660 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
27670 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
27680 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
27690 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
276a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
276b0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
276c0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
276d0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
276e0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
276f0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
27700 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
27710 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
27720 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
27730 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
27740 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
27750 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
27760 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
27770 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
27780 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
27790 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
277a0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
277b0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
277c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
277d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
277e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
277f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
27800 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
27810 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27820 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
27830 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
27840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27850 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
27860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
27870 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
27880 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
27890 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
278a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
278b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
278c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
278d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
278e0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
278f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
27900 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
27910 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27920 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
27930 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
27940 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27950 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
27960 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27970 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
27980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
27990 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
279a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
279b0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
279c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
279d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
279e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
279f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
27a00 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
27a10 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
27a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27a30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
27a40 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
27a50 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
27a60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a70 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
27a80 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
27a90 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
27aa0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
27ab0 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a  d no errors or.*
27ac0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
27ad0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
27ae0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
27af0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
27b00 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
27b10 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
27b20 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
27b30 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
27b40 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
27b50 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
27b60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
27b70 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
27b80 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
27b90 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
27ba0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
27bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
27bc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
27bd0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
27be0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
27bf0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
27c00 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
27c10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27c20 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
27c30 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
27c40 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
27c50 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
27c60 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
27c70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27c80 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
27c90 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
27ca0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
27cb0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
27cc0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
27cd0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
27ce0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
27cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
27d00 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
27d10 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
27d20 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
27d30 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
27d40 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
27d50 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
27d60 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
27d70 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
27d80 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
27d90 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
27da0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
27db0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
27dc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
27dd0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
27de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27df0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
27e00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
27e10 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
27e20 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
27e30 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
27e40 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
27e50 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
27e60 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
27e70 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
27e80 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
27e90 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
27ea0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
27eb0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
27ec0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
27ed0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
27ee0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
27ef0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
27f00 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
27f10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
27f20 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
27f30 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
27f40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27f50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
27f60 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
27f70 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
27f80 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
27f90 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
27fa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
27fb0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
27fc0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
27fd0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
27fe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27ff0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
28000 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
28010 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
28020 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
28030 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
28040 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
28050 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
28060 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
28070 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
28080 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
28090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
280a0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
280b0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
280c0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
280d0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
280e0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
280f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
28100 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
28110 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28120 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
28130 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
28140 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
28150 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
28160 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
28170 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
28180 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
28190 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
281a0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
281b0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
281c0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
281d0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
281e0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
281f0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
28200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
28210 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
28220 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
28230 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
28240 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
28250 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
28260 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
28270 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
28280 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
28290 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
282a0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
282b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
282c0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
282d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
282e0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
282f0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
28300 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28310 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28320 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
28330 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
28340 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
28350 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
28360 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
28370 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
28380 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
28390 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
283a0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
283b0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
283c0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
283d0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
283e0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
283f0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
28400 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
28410 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
28420 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
28430 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
28440 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
28450 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
28460 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
28470 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
28480 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
28490 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
284a0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
284b0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
284c0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
284d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
284e0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
284f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
28500 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
28510 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
28520 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
28530 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
28540 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
28550 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
28560 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
28570 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
28580 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
28590 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
285a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
285b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
285c0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
285d0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
285e0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
285f0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
28600 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
28610 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
28620 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
28630 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
28640 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28650 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
28660 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
28670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28680 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
28690 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
286a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
286b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
286c0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
286d0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
286e0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
286f0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
28700 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
28710 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
28720 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
28730 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
28740 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
28750 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
28760 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
28770 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
28780 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
28790 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
287a0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
287b0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
287c0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
287d0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
287e0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
287f0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
28800 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
28810 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
28820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
28830 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
28840 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
28850 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
28860 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
28870 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
28880 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
28890 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
288a0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
288b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
288c0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
288d0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
288e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
288f0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
28900 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
28910 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
28920 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
28930 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
28940 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
28950 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
28960 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
28970 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
28980 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
28990 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
289a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
289b0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
289c0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
289d0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
289e0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
289f0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
28a00 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
28a10 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
28a20 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53  meters.  Every S
28a30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
28a40 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
28a50 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
28a60 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  ** with UTF-8, U
28a70 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
28a80 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
28a90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
28aa0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
28ab0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
28ac0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
28ad0 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70  another.  ^An ap
28ae0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a  plication may.**
28af0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
28b00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
28b10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
28b20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
28b30 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
28b40 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
28b50 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
28b60 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
28b70 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
28b80 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
28b90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
28ba0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
28bb0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
28bc0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
28bd0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
28be0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
28bf0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
28c00 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
28c10 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
28c20 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
28c30 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
28c40 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
28c50 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
28c60 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
28c70 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
28c80 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
28c90 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
28ca0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ANY]..**.** ^(Th
28cb0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
28cc0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
28cd0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
28ce0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
28cf0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
28d00 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
28d10 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
28d20 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
28d30 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
28d40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
28d50 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
28d60 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
28d70 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
28d80 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
28d90 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
28da0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
28db0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
28dc0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
28dd0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
28de0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
28df0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
28e00 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
28e10 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
28e20 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
28e30 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
28e40 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
28e50 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
28e60 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
28e70 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
28e80 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
28e90 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
28ea0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
28eb0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
28ec0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
28ed0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
28ee0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
28ef0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
28f00 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
28f10 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
28f20 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
28f30 70 6f 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c 20  poiners for all 
28f40 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
28f50 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
28f60 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
28f70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28f80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28f90 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
28fa0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
28fb0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
28fc0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
28fd0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
28fe0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
28ff0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
29000 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
29010 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
29020 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
29030 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
29040 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
29050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
29060 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
29070 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
29080 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
29090 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
290a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
290b0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
290c0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
290d0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
290e0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
290f0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
29100 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
29110 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
29120 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
29130 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
29140 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
29150 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
29160 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
29170 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29180 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29190 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
291a0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
291b0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
291c0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
291d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
291e0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
291f0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
29200 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
29210 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
29220 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
29230 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
29240 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
29250 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
29260 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
29270 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
29280 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
29290 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
292a0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
292b0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
292c0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
292d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
292e0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
292f0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
29300 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
29310 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
29320 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
29330 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
29340 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
29350 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
29360 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
29370 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
29380 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
29390 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
293a0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
293b0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
293c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
293d0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
293e0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
293f0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
29400 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
29410 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
29420 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
29430 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
29440 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
29450 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
29460 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
29470 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
29480 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
29490 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
294a0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
294b0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
294c0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
294d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
294e0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
294f0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
29500 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29510 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
29520 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
29530 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
29540 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
29550 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
29560 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
29570 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29580 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
29590 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
295a0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
295b0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
295c0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
295d0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
295e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
295f0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
29600 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
29610 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
29620 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
29630 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
29640 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
29650 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
29660 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
29670 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
29680 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
29690 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
296a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
296b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
296c0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
296d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
296e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
296f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
29700 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
29710 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
29720 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
29730 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
29740 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
29750 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
29760 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
29770 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
29780 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
29790 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
297a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
297b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
297c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
297d0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
297e0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
297f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29800 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
29810 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
29820 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
29830 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
29840 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
29850 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
29860 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
29870 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29880 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
29890 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
298a0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
298b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
298c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
298d0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
298e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
298f0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
29900 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
29910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
29920 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
29930 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
29940 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
29950 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
29960 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
29970 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
29980 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
29990 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
299a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
299b0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
299c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
299d0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
299e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
299f0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
29a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
29a10 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
29a20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
29a30 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
29a40 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
29a50 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
29a60 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
29a70 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
29a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
29a90 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
29aa0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
29ab0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29ac0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
29ad0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
29ae0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
29af0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
29b00 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
29b10 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
29b20 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
29b30 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
29b40 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
29b50 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
29b60 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
29b70 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
29b80 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
29b90 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
29ba0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
29bb0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
29bc0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
29bd0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
29be0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
29bf0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
29c00 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
29c10 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
29c20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
29c30 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
29c40 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
29c50 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
29c60 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
29c70 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
29c80 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29c90 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
29ca0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
29cb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
29cc0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
29cd0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
29ce0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
29cf0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
29d00 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
29d10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
29d20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
29d30 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
29d40 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
29d50 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
29d60 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
29d70 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
29d80 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
29d90 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
29da0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
29db0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
29dc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
29dd0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
29de0 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
29df0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
29e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
29e10 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
29e20 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
29e30 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
29e40 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
29e50 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
29e60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
29e70 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
29e80 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
29e90 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
29ea0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
29eb0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
29ec0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
29ed0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
29ee0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
29ef0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
29f00 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
29f10 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
29f20 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
29f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
29f40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
29f50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
29f60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
29f70 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
29f80 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
29f90 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
29fa0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
29fb0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
29fc0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
29fd0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
29fe0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
29ff0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2a000 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a010 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2a020 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2a030 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a040 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2a050 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2a060 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2a070 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a080 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2a090 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2a0a0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2a0b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2a0c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a0d0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2a0e0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2a0f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a100 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2a110 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2a120 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2a130 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2a140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2a150 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2a160 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2a170 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
2a180 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2a190 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2a1a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
2a1b0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2a1c0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
2a1d0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
2a1e0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2a1f0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2a200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a210 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
2a220 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2a230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2a240 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2a250 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2a260 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2a270 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a280 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
2a290 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
2a2a0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
2a2b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
2a2c0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2a2d0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
2a2e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2a2f0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
2a300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a310 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
2a320 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
2a330 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
2a340 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2a350 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2a360 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2a370 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
2a380 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2a390 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2a3a0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2a3b0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2a3c0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2a3d0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2a3e0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2a3f0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2a400 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2a410 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2a420 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2a430 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2a440 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2a450 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2a460 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2a470 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2a480 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2a490 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2a4a0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2a4b0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2a4c0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2a4d0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2a4e0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2a4f0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2a500 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2a510 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2a520 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2a530 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2a540 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2a550 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2a560 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2a570 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2a580 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
2a590 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2a5a0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2a5b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a5c0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2a5d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2a5e0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2a5f0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2a600 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2a610 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2a620 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2a630 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2a640 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2a650 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2a660 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2a670 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
2a680 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a690 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2a6a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2a6b0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
2a6c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
2a6d0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
2a6e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
2a6f0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
2a700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a710 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2a720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a730 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2a740 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2a750 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2a760 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2a770 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2a780 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2a790 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2a7a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2a7b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2a7c0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2a7d0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2a7e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2a7f0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2a800 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2a810 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2a820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a830 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2a840 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2a850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a860 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2a870 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2a880 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2a890 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2a8a0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2a8b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2a8c0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2a8d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2a8e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2a8f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2a900 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2a910 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2a920 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2a930 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2a940 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2a950 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2a960 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
2a970 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2a980 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2a990 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2a9a0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
2a9b0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
2a9c0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2a9d0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2a9e0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
2a9f0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2aa00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2aa10 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
2aa20 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
2aa30 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2aa40 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
2aa50 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
2aa60 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
2aa70 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
2aa80 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2aa90 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2aaa0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
2aab0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
2aac0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2aad0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2aae0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2aaf0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2ab00 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2ab10 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
2ab20 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2ab30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
2ab40 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
2ab50 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
2ab60 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
2ab70 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2ab80 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2ab90 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
2aba0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
2abb0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
2abc0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
2abd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
2abe0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
2abf0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
2ac00 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
2ac10 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
2ac20 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
2ac30 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
2ac40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
2ac50 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
2ac60 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
2ac70 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
2ac80 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
2ac90 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
2aca0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2acb0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
2acc0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
2acd0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
2ace0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
2acf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ad00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ad10 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2ad20 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
2ad30 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
2ad40 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
2ad50 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
2ad60 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
2ad70 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
2ad80 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
2ad90 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
2ada0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
2adb0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2adc0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
2add0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
2ade0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2adf0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
2ae00 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
2ae10 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
2ae20 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
2ae30 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2ae40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ae50 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
2ae60 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
2ae70 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2ae80 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
2ae90 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
2aea0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2aeb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2aec0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2aed0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
2aee0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
2aef0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2af00 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
2af10 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
2af20 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2af30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2af40 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2af50 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2af60 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2af70 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2af80 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2af90 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2afa0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2afb0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
2afc0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
2afd0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2afe0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2aff0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2b000 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b010 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2b020 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2b030 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2b040 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2b050 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2b060 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2b070 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2b080 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2b090 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2b0a0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2b0b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2b0c0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2b0d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2b0e0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2b0f0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2b100 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2b110 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2b120 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2b130 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2b140 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2b150 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2b160 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b170 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2b180 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2b190 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2b1a0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2b1b0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2b1c0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2b1d0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2b1e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2b1f0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2b200 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2b210 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2b220 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2b230 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b240 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2b250 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2b260 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
2b270 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2b280 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2b290 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
2b2a0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
2b2b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
2b2c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
2b2d0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
2b2e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b2f0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2b300 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
2b310 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2b320 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
2b330 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2b340 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2b350 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b360 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2b370 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b380 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2b390 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2b3a0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2b3b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2b3c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2b3d0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2b3e0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2b3f0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2b400 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2b410 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2b420 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2b430 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
2b440 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
2b450 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
2b460 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
2b470 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
2b480 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
2b490 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
2b4a0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
2b4b0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
2b4c0 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
2b4d0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
2b4e0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
2b4f0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
2b500 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
2b510 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
2b520 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
2b530 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
2b540 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2b550 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2b560 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2b570 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2b580 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2b590 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2b5a0 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2b5b0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2b5c0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2b5d0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2b5e0 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2b5f0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2b600 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
2b610 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
2b620 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2b630 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
2b640 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
2b650 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2b660 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
2b670 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
2b680 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2b690 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2b6a0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
2b6b0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
2b6c0 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
2b6d0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
2b6e0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
2b6f0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2b700 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
2b710 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2b720 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b730 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2b740 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
2b750 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
2b760 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2b770 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
2b780 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
2b790 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
2b7a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2b7b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2b7c0 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
2b7d0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
2b7e0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
2b7f0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
2b800 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
2b810 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
2b820 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
2b830 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
2b840 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
2b850 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
2b860 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
2b870 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2b880 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
2b890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2b8a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b8b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2b8c0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2b8d0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
2b8e0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
2b8f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
2b900 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
2b910 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2b920 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2b930 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b940 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2b950 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2b960 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2b970 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2b980 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2b990 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2b9a0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2b9b0 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
2b9c0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2b9d0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2b9e0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2b9f0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
2ba00 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
2ba10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
2ba20 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
2ba30 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
2ba40 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
2ba50 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
2ba60 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2ba70 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
2ba80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
2ba90 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
2baa0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
2bab0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
2bac0 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
2bad0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
2bae0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
2baf0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
2bb00 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
2bb10 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
2bb20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
2bb30 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
2bb40 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
2bb50 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
2bb60 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
2bb70 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
2bb80 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
2bb90 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
2bba0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
2bbb0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
2bbc0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
2bbd0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
2bbe0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
2bbf0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
2bc00 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
2bc10 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
2bc20 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
2bc30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2bc40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2bc50 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2bc60 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2bc70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2bc80 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
2bc90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
2bca0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2bcb0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2bcc0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2bcd0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
2bce0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2bcf0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
2bd00 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
2bd10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bd20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
2bd30 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
2bd40 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
2bd50 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
2bd60 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
2bd70 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
2bd80 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
2bd90 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
2bda0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
2bdb0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2bdc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2bdd0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
2bde0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
2bdf0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
2be00 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
2be10 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2be20 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
2be30 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
2be40 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
2be50 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
2be60 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
2be70 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
2be80 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
2be90 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
2bea0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
2beb0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
2bec0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
2bed0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
2bee0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
2bef0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2bf00 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
2bf10 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
2bf20 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
2bf30 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
2bf40 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
2bf50 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
2bf60 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
2bf70 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
2bf80 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
2bf90 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
2bfa0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
2bfb0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
2bfc0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
2bfd0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
2bfe0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2bff0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
2c000 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
2c010 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
2c020 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
2c030 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
2c040 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
2c050 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
2c060 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
2c070 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2c080 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
2c090 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
2c0a0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
2c0b0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
2c0c0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2c0d0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
2c0e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c0f0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2c100 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c110 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2c120 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
2c130 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2c140 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2c150 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
2c160 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
2c170 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
2c180 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
2c190 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
2c1a0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
2c1b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
2c1c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c1d0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
2c1e0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
2c1f0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
2c200 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
2c210 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2c220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c230 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2c240 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2c250 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2c260 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2c270 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2c280 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
2c290 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
2c2a0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
2c2b0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
2c2c0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
2c2d0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
2c2e0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
2c2f0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
2c300 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
2c310 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c320 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
2c330 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
2c340 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2c350 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c360 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2c370 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
2c380 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
2c390 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
2c3a0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
2c3b0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
2c3c0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
2c3d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
2c3e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c3f0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2c400 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2c410 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2c420 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c430 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2c440 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2c450 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2c460 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2c470 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2c480 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c490 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2c4a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c4b0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
2c4c0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
2c4d0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
2c4e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
2c4f0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
2c500 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2c510 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
2c520 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
2c530 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2c540 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c550 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
2c560 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2c570 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
2c580 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
2c590 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
2c5a0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2c5b0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2c5c0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2c5d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c5e0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
2c5f0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
2c600 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
2c610 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2c620 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
2c630 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2c640 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
2c650 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2c660 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2c670 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c680 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2c690 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c6a0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
2c6b0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2c6c0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
2c6d0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
2c6e0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2c6f0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2c700 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2c710 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2c720 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2c730 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
2c740 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c750 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
2c760 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
2c770 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
2c780 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
2c790 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2c7a0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2c7b0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
2c7c0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
2c7d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c7e0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2c7f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c800 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
2c810 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
2c820 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2c830 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2c840 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2c850 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2c860 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2c870 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2c880 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2c890 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2c8a0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2c8b0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2c8c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2c8d0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
2c8e0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
2c8f0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
2c900 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
2c910 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
2c920 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
2c930 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
2c940 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
2c950 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
2c960 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
2c970 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
2c980 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
2c990 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2c9a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2c9b0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
2c9c0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2c9d0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
2c9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c9f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
2ca00 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
2ca10 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2ca20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2ca30 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2ca40 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
2ca50 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
2ca60 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
2ca70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ca80 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
2ca90 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2caa0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2cab0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2cac0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
2cad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2cae0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
2caf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2cb00 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
2cb10 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2cb20 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2cb30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2cb40 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2cb50 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
2cb60 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2cb70 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2cb80 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2cb90 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
2cba0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2cbb0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2cbc0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2cbd0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2cbe0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cbf0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2cc00 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
2cc10 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2cc20 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2cc30 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2cc40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cc50 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2cc60 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2cc70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2cc80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2cc90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2cca0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2ccb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ccc0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2ccd0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
2cce0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
2ccf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cd00 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2cd10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cd20 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2cd30 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2cd40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2cd50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2cd60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2cd70 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2cd80 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2cd90 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2cda0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2cdb0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2cdc0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2cdd0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2cde0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2cdf0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2ce00 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
2ce10 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
2ce20 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
2ce30 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
2ce40 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
2ce50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ce60 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2ce70 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
2ce80 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2ce90 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2cea0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2ceb0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2cec0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2ced0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2cee0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2cef0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
2cf00 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2cf10 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2cf20 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2cf30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2cf40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cf50 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2cf60 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2cf70 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2cf80 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2cf90 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2cfa0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2cfb0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2cfc0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2cfd0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2cfe0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2cff0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2d000 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2d010 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2d020 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d030 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2d040 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2d050 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
2d060 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
2d070 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
2d080 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
2d090 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
2d0a0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
2d0b0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
2d0c0 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
2d0d0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2d0e0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2d0f0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2d100 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2d110 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2d120 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
2d130 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2d140 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2d150 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2d160 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2d170 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
2d180 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2d190 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
2d1a0 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
2d1b0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2d1c0 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
2d1d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
2d1e0 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
2d1f0 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
2d200 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
2d210 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2d220 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2d230 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2d240 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2d250 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2d260 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2d270 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2d280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2d290 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2d2a0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2d2b0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
2d2c0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
2d2d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
2d2e0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
2d2f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
2d300 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2d310 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
2d320 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
2d330 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d340 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2d350 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2d360 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2d370 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2d380 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2d390 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2d3a0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2d3b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d3c0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2d3d0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2d3e0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
2d3f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d400 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2d410 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2d420 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2d430 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2d440 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2d450 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
2d460 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
2d470 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
2d480 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
2d490 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
2d4a0 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
2d4b0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
2d4c0 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
2d4d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d4e0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2d4f0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2d500 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2d510 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d520 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
2d530 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
2d540 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
2d550 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d560 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
2d570 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
2d580 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
2d590 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2d5a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
2d5b0 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
2d5c0 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
2d5d0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
2d5e0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
2d5f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2d600 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
2d610 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
2d620 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
2d630 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
2d640 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2d650 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2d660 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
2d670 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d680 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2d690 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d6a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d6b0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
2d6c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
2d6d0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
2d6e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d6f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d700 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2d710 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2d720 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2d730 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2d740 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2d750 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d760 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d770 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
2d780 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2d790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2d7a0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
2d7b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2d7c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d7d0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
2d7e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d7f0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2d800 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
2d810 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d820 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2d830 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
2d840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d850 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2d860 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d870 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
2d880 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2d890 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d8a0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2d8b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2d8c0 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2d8d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2d8e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d8f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
2d900 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2d910 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2d920 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2d930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d940 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2d950 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d960 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2d970 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2d980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d990 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2d9a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d9b0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2d9c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d9d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d9e0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
2d9f0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2da00 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
2da10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2da20 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
2da30 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
2da40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2da50 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
2da60 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
2da70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2da80 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
2da90 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
2daa0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
2dab0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2dac0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2dad0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
2dae0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2daf0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2db00 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2db10 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
2db20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2db30 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2db40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2db50 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
2db60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2db70 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
2db80 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
2db90 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
2dba0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2dbb0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
2dbc0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
2dbd0 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
2dbe0 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
2dbf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
2dc00 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
2dc10 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
2dc20 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
2dc30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
2dc40 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
2dc50 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
2dc60 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
2dc70 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
2dc80 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
2dc90 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
2dca0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
2dcb0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2dcc0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
2dcd0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
2dce0 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
2dcf0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
2dd00 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
2dd10 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
2dd20 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
2dd30 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
2dd40 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
2dd50 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
2dd60 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
2dd70 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
2dd80 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
2dd90 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
2dda0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2ddb0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
2ddc0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
2ddd0 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
2dde0 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
2ddf0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
2de00 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
2de10 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
2de20 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
2de30 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
2de40 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
2de50 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
2de60 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
2de70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2de80 70 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c 69  pArg, is a appli
2de90 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2dea0 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
2deb0 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
2dec0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2ded0 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
2dee0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
2def0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
2df00 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2df10 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
2df20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2df30 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2df40 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
2df50 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
2df60 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
2df70 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
2df80 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2df90 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
2dfa0 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
2dfb0 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
2dfc0 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
2dfd0 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
2dfe0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
2dff0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2e000 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
2e010 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
2e020 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
2e030 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
2e040 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2e050 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
2e060 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
2e070 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e080 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
2e090 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
2e0a0 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
2e0b0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
2e0c0 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
2e0d0 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
2e0e0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2e0f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
2e100 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
2e110 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
2e120 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2e130 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
2e140 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
2e150 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2e160 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
2e170 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
2e180 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
2e190 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
2e1a0 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
2e1b0 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
2e1c0 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
2e1d0 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
2e1e0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
2e1f0 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
2e200 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
2e210 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
2e220 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2e230 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
2e240 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
2e250 79 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  y return the sam
2e260 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
2e270 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
2e280 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
2e290 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
2e2a0 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
2e2b0 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
2e2c0 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
2e2d0 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
2e2e0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
2e2f0 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
2e300 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
2e310 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
2e320 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
2e330 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
2e340 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
2e350 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e360 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
2e370 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
2e380 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
2e390 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
2e3a0 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
2e3b0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
2e3c0 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
2e3d0 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
2e3e0 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
2e3f0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
2e400 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
2e410 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
2e420 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
2e430 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
2e440 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
2e450 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
2e460 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
2e470 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
2e480 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
2e490 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2e4a0 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
2e4b0 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
2e4c0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
2e4d0 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
2e4e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2e4f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e500 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2e510 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
2e520 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e530 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
2e540 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
2e550 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
2e560 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
2e570 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
2e580 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
2e590 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2e5a0 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
2e5b0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
2e5c0 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
2e5d0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
2e5e0 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
2e5f0 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
2e600 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
2e610 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
2e620 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2e630 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
2e640 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
2e650 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
2e660 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
2e670 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
2e680 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
2e690 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
2e6a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e6b0 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
2e6c0 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
2e6d0 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
2e6e0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
2e6f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2e700 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
2e710 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
2e720 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
2e730 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
2e740 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
2e750 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
2e760 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2e770 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
2e780 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
2e790 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
2e7a0 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
2e7b0 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
2e7c0 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
2e7d0 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
2e7e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
2e7f0 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
2e800 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
2e810 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
2e820 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
2e830 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
2e840 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
2e850 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
2e860 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
2e870 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2e880 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
2e890 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2e8a0 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
2e8b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2e8c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
2e8d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2e8e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2e8f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2e900 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
2e910 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2e920 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2e930 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2e940 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
2e950 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e960 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
2e970 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2e980 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
2e990 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2e9a0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
2e9b0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2e9c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2e9d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2e9e0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2e9f0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2ea00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2ea10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2ea20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2ea30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
2ea40 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
2ea50 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2ea60 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2ea70 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2ea80 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2ea90 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2eaa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2eab0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
2eac0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
2ead0 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
2eae0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
2eaf0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2eb00 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
2eb10 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
2eb20 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
2eb30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2eb40 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
2eb50 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
2eb60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2eb70 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
2eb80 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
2eb90 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
2eba0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2ebb0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
2ebc0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
2ebd0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2ebe0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2ebf0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2ec00 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2ec10 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2ec20 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2ec30 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2ec40 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2ec50 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2ec60 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
2ec70 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ec80 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
2ec90 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
2eca0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
2ecb0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
2ecc0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
2ecd0 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
2ece0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
2ecf0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
2ed00 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
2ed10 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
2ed20 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
2ed30 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
2ed40 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
2ed50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
2ed60 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
2ed70 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
2ed80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2ed90 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2eda0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
2edb0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2edc0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
2edd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2ede0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
2edf0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
2ee00 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2ee10 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2ee20 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2ee30 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
2ee40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2ee50 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
2ee60 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
2ee70 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
2ee80 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2ee90 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
2eea0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
2eeb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2eec0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2eed0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
2eee0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2eef0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
2ef00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2ef10 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
2ef20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
2ef30 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
2ef40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ef50 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
2ef60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ef70 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
2ef80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2ef90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2efa0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2efb0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2efc0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
2efd0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
2efe0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2eff0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2f000 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
2f010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2f020 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2f030 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2f040 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
2f050 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2f060 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2f070 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
2f080 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
2f090 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
2f0a0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
2f0b0 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
2f0c0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
2f0d0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
2f0e0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
2f0f0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
2f100 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
2f110 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2f120 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2f130 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2f140 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2f150 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2f160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
2f170 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2f180 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2f190 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2f1a0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2f1b0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2f1c0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2f1d0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
2f1e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
2f1f0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
2f200 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
2f210 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
2f220 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
2f230 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
2f240 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
2f250 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
2f260 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
2f270 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
2f280 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
2f290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2f2a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2f2b0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2f2c0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2f2d0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2f2e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2f2f0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
2f300 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2f310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f320 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2f330 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2f340 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2f350 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2f360 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
2f370 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
2f380 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
2f390 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
2f3a0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2f3b0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2f3c0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
2f3d0 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
2f3e0 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
2f3f0 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
2f400 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
2f410 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2f420 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2f430 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2f440 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
2f450 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
2f460 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
2f470 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2f480 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
2f490 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
2f4a0 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
2f4b0 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
2f4c0 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
2f4d0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2f4e0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2f4f0 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
2f500 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
2f510 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
2f520 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
2f530 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2f540 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
2f550 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2f560 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
2f570 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f580 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
2f590 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
2f5a0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
2f5b0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
2f5c0 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
2f5d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
2f5e0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
2f5f0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
2f600 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
2f610 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2f620 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
2f630 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
2f640 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
2f650 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
2f660 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
2f670 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
2f680 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
2f690 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
2f6a0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
2f6b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
2f6c0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
2f6d0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
2f6e0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
2f6f0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
2f700 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
2f710 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
2f720 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
2f730 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
2f740 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
2f750 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
2f760 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
2f770 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
2f780 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
2f790 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
2f7a0 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
2f7b0 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
2f7c0 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
2f7d0 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
2f7e0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
2f7f0 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
2f800 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
2f810 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
2f820 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
2f830 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
2f840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f850 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
2f860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2f870 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
2f880 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
2f890 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
2f8a0 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
2f8b0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
2f8c0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
2f8d0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
2f8e0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
2f8f0 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
2f900 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
2f910 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
2f920 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
2f930 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
2f940 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
2f950 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
2f960 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
2f970 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
2f980 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
2f990 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2f9a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2f9b0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
2f9c0 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
2f9d0 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
2f9e0 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
2f9f0 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
2fa00 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
2fa10 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
2fa20 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2fa30 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
2fa40 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
2fa50 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
2fa60 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2fa70 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2fa80 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2fa90 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
2faa0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
2fab0 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
2fac0 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
2fad0 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
2fae0 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
2faf0 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
2fb00 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
2fb10 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
2fb20 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
2fb30 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
2fb40 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
2fb50 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
2fb60 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
2fb70 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
2fb80 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
2fb90 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
2fba0 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
2fbb0 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
2fbc0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2fbd0 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
2fbe0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
2fbf0 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
2fc00 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
2fc10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2fc20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
2fc30 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
2fc40 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
2fc50 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2fc60 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
2fc70 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
2fc80 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
2fc90 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
2fca0 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
2fcb0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2fcc0 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
2fcd0 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
2fce0 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
2fcf0 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
2fd00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
2fd10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
2fd20 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
2fd30 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
2fd40 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
2fd50 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
2fd60 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
2fd70 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
2fd80 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2fd90 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2fda0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
2fdb0 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
2fdc0 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
2fdd0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2fde0 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
2fdf0 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
2fe00 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
2fe10 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
2fe20 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
2fe30 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
2fe40 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
2fe50 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
2fe60 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
2fe70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fe80 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2fe90 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
2fea0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
2feb0 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
2fec0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
2fed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2fee0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
2fef0 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
2ff00 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
2ff10 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2ff20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
2ff30 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2ff40 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
2ff50 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
2ff60 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
2ff70 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2ff80 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
2ff90 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
2ffa0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
2ffb0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
2ffc0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
2ffd0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
2ffe0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
2fff0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
30000 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
30010 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
30020 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
30030 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
30040 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
30050 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
30060 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
30070 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
30080 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
30090 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
300a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
300b0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
300c0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
300d0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
300e0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
300f0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
30100 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
30110 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
30120 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
30130 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
30140 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
30150 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
30160 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
30170 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
30180 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
30190 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
301a0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
301b0 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
301c0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
301d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
301e0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
301f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30200 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
30210 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
30220 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
30230 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ent.**.** ^The s
30240 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
30250 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30260 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
30270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
30280 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
30290 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
302a0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
302b0 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20   ^The [database 
302c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
302d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
302e0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
302f0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
30300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
30310 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  * that was the f
30320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
30330 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
30340 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
30350 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
30360 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
30370 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
30380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30390 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
303a0 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
303b0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
303c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
303d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
303e0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
303f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30400 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
30410 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30420 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30430 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
30440 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
30450 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
30460 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
30470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30480 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
30490 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
304a0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
304b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
304c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
304d0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
304e0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
304f0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
30500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30510 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
30520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30530 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
30540 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
30550 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
30560 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
30570 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
30580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
30590 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
305a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
305b0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
305c0 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
305d0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
305e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
305f0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
30600 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
30610 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
30620 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
30630 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
30640 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
30650 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
30660 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30670 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
30680 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
30690 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
306a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
306b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
306c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
306d0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
306e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
306f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
30700 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
30710 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
30720 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
30730 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
30740 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
30750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
30760 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
30770 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
30780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
30790 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
307a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
307b0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
307c0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
307d0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
307e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
307f0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
30800 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30810 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
30820 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
30830 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
30840 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
30850 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
30860 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
30870 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
30880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30890 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
308a0 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
308b0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
308c0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
308d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
308e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
308f0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
30900 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
30910 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
30920 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
30930 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
30940 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
30950 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
30960 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
30970 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
30980 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
30990 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
309a0 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
309b0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
309c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
309d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
309e0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
309f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30a00 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
30a10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
30a20 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
30a30 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
30a40 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
30a50 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
30a60 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
30a70 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
30a80 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
30a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30aa0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
30ab0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
30ac0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
30ad0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
30ae0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
30af0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
30b00 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
30b10 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
30b20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
30b30 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
30b40 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
30b50 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
30b60 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
30b70 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
30b80 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
30b90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30ba0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
30bb0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
30bc0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
30bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
30be0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
30bf0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
30c00 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
30c10 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e  *.** ^Registerin
30c20 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
30c30 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
30c40 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
30c50 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  When the commit 
30c60 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f  hook callback ro
30c70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
30c80 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  ro, the [COMMIT]
30c90 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  .** operation is
30ca0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74   allowed to cont
30cb0 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20  inue normally.  
30cc0 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  ^If the commit h
30cd0 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  ook.** returns n
30ce0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
30cf0 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f  e [COMMIT] is co
30d00 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b  nverted into a [
30d10 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54  ROLLBACK]..** ^T
30d20 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
30d30 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
30d40 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
30d50 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
30d60 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
30d70 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
30d80 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
30d90 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
30da0 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
30db0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
30dc0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
30dd0 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
30de0 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
30df0 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
30e00 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
30e10 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
30e20 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
30e30 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
30e40 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
30e50 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
30e60 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
30e70 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65  o occur..** ^The
30e80 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
30e90 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
30ea0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
30eb0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
30ec0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
30ed0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
30ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30ef0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
30f00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
30f10 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
30f20 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61  _hook()] interfa
30f30 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ce..*/.void *sql
30f40 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
30f50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
30f60 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
30f70 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
30f80 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
30f90 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
30fa0 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
30fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30fc0 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
30fd0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
30fe0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
30ff0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
31000 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
31010 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
31020 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
31030 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
31040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31050 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
31060 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31070 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
31080 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
31090 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
310a0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
310b0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
310c0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
310d0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
310e0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
310f0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
31100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
31110 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
31120 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
31130 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
31140 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
31150 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
31160 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
31170 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
31180 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
31190 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
311a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
311b0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
311c0 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
311d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
311e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
311f0 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  )..** ^The secon
31200 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
31210 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
31220 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
31230 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
31240 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
31250 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
31260 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
31270 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
31280 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
31290 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
312a0 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
312b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
312c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
312d0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
312e0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
312f0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
31300 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
31310 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
31320 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61  ** ^The final ca
31330 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
31340 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
31350 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e  of the row..** ^
31360 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
31370 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
31380 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66  s the [rowid] af
31390 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74  ter the update t
313a0 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
313b0 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68  * ^(The update h
313c0 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
313d0 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
313e0 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
313f0 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
31400 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
31410 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
31420 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a  quence).)^.**.**
31430 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74   ^In the current
31440 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
31450 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
31460 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  .** is not invok
31470 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74  ed when duplicat
31480 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  ion rows are del
31490 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20  eted because of 
314a0 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49  an.** [ON CONFLI
314b0 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  CT | ON CONFLICT
314c0 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65   REPLACE] clause
314d0 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75  .  ^Nor is the u
314e0 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e  pdate hook.** in
314f0 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20  voked when rows 
31500 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e  are deleted usin
31510 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20  g the [truncate 
31520 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a  optimization]..*
31530 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73  * The exceptions
31540 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73   defined in this
31550 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74   paragraph might
31560 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
31570 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
31580 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
31590 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
315a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
315b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
315c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
315d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
315e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
315f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
31600 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
31610 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
31620 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
31630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31640 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
31650 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
31660 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
31670 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
31680 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
31690 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
316a0 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
316b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
316c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
316d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
316e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
316f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
31700 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
31710 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
31720 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
31730 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
31740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31750 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43  _update_hook(D,C
31760 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ,P) function.** 
31770 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
31780 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
31790 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a  previous call.**
317a0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
317b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
317c0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
317d0 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
317e0 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  all on D..**.** 
317f0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
31800 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
31810 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  k()] and [sqlite
31820 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
31830 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  )].** interfaces
31840 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31850 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
31860 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
31870 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
31880 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
31890 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
318a0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
318b0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
318c0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
318d0 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
318e0 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a  d Pager Cache.**
318f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
31900 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20  ed cache}.**.** 
31910 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
31920 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
31930 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
31940 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
31950 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
31960 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
31970 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
31980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31990 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
319a0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
319b0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
319c0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
319d0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
319e0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
319f0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
31a00 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
31a10 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
31a20 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
31a30 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
31a40 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
31a50 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
31a60 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
31a70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
31a80 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
31a90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
31aa0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
31ab0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
31ac0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
31ad0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
31ae0 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
31af0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
31b00 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
31b10 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
31b20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
31b30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
31b40 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
31b50 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
31b60 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
31b70 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
31b80 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
31b90 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
31ba0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
31bb0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
31bc0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
31bd0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
31be0 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
31bf0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
31c00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
31c10 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
31c20 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
31c30 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
31c40 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
31c50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
31c60 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
31c70 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
31c80 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
31c90 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
31ca0 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
31cb0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
31cc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
31cd0 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
31ce0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
31cf0 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
31d00 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
31d10 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
31d20 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
31d30 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
31d40 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
31d50 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Mode].*/.int sql
31d60 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
31d70 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
31d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31d90 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20  Attempt To Free 
31da0 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a  Heap Memory.**.*
31db0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31dc0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
31dd0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
31de0 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  ts to free N byt
31df0 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65  es.** of heap me
31e00 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
31e10 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
31e20 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
31e30 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79  tions.** held by
31e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
31e50 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20  brary.   Memory 
31e60 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
31e70 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
31e80 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
31e90 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
31ea0 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
31eb0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
31ec0 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   ^sqlite3_releas
31ed0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
31ee0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31ef0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
31f00 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
31f10 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
31f20 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
31f30 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
31f40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31f50 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
31f60 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e  ) routine is a n
31f70 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a  o-op returning z
31f80 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  ero.** if SQLite
31f90 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64   is not compiled
31fa0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   with [SQLITE_EN
31fb0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
31fc0 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20  GEMENT]..*/.int 
31fd0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
31fe0 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
31ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d  .** CAPI3REF: Im
32000 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
32010 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20  Heap Size.**.** 
32020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66  ^The sqlite3_sof
32030 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
32040 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32050 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74  and/or queries t
32060 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74  he.** soft limit
32070 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
32080 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
32090 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
320a0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
320b0 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65  * ^SQLite strive
320c0 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d  s to keep heap m
320d0 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f  emory utilizatio
320e0 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74  n below the soft
320f0 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62   heap.** limit b
32100 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e  y reducing the n
32110 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68  umber of pages h
32120 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20  eld in the page 
32130 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70  cache.** as heap
32140 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61   memory usages a
32150 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69  pproaches the li
32160 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66  mit..** ^The sof
32170 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
32180 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65  "soft" because e
32190 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74  ven though SQLit
321a0 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61  e strives to sta
321b0 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c  y.** below the l
321c0 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78  imit, it will ex
321d0 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72  ceed the limit r
321e0 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72  ather than gener
321f0 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54  ate.** an [SQLIT
32200 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20  E_NOMEM] error. 
32210 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
32220 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
32230 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69  imit .** is advi
32240 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
32250 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c   ^The return val
32260 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
32270 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
32280 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20  4() is the size 
32290 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  of.** the soft h
322a0 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20  eap limit prior 
322b0 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49  to the call.  ^I
322c0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
322d0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
322e0 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69  then no change i
322f0 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f  s made to the so
32300 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
32310 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65  Hence, the curre
32320 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  nt.** size of th
32330 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
32340 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
32350 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a  ned by invoking.
32360 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  ** sqlite3_soft_
32370 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77  heap_limit64() w
32380 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61  ith a negative a
32390 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
323a0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
323b0 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74  N is zero then t
323c0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
323d0 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  it is disabled..
323e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74  **.** ^(The soft
323f0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e   heap limit is n
32400 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74  ot enforced in t
32410 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
32420 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20  mentation.** if 
32430 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66  one or more of f
32440 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69  ollowing conditi
32450 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a  ons are true:.**
32460 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
32470 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   The soft heap l
32480 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a  imit is set to z
32490 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d  ero..** <li> Mem
324a0 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
324b0 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  s disabled using
324c0 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
324d0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73  f the.**      [s
324e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
324f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
32500 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74  MSTATUS],...) st
32510 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  art-time option 
32520 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  and.**      the 
32530 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
32540 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69  MEMSTATUS] compi
32550 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
32560 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72  ** <li> An alter
32570 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68  native page cach
32580 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32590 20 69 73 20 73 70 65 63 69 66 65 64 20 75 73 69   is specifed usi
325a0 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
325b0 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
325c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
325d0 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e  E],...)..** <li>
325e0 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20   The page cache 
325f0 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69  allocates from i
32600 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f  ts own memory po
32610 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20  ol supplied.**  
32620 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
32630 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
32640 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
32650 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68  ],...) rather th
32660 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20  an.**      from 
32670 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75  the heap..** </u
32680 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e  l>)^.**.** Begin
32690 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
326a0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20   version 3.7.3, 
326b0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
326c0 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a  mit is enforced.
326d0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
326e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
326f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
32700 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
32710 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  MENT].** compile
32720 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
32730 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b  invoked.  With [
32740 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
32750 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
32760 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  ,.** the soft he
32770 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f  ap limit is enfo
32780 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65  rced on every me
32790 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  mory allocation.
327a0 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51    Without.** [SQ
327b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
327c0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20  RY_MANAGEMENT], 
327d0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
327e0 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f  mit is only enfo
327f0 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d  rced.** when mem
32800 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
32810 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63   by the page cac
32820 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67  he.  Testing sug
32830 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75  gests that becau
32840 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63  se.** the page c
32850 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64  ache is the pred
32860 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75  ominate memory u
32870 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d  ser in SQLite, m
32880 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
32890 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65  ons will achieve
328a0 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68   adequate soft h
328b0 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63  eap limit enforc
328c0 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a  ement without.**
328d0 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c   the use of [SQL
328e0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
328f0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
32900 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73  *.** The circums
32910 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69  tances under whi
32920 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  ch SQLite will e
32930 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20  nforce the soft 
32940 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a  heap limit may.*
32950 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74  * changes in fut
32960 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
32970 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74  SQLite..*/.sqlit
32980 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
32990 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
329a0 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64(sqlite3_int64
329b0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
329c0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
329d0 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74   Soft Heap Limit
329e0 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45   Interface.** DE
329f0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
32a00 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61  his is a depreca
32a10 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  ted version of t
32a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
32a30 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
32a40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
32a50 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
32a60 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73  provided for his
32a70 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
32a80 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20  ility.** only.  
32a90 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  All new applicat
32aa0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20  ions should use 
32ab0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
32ac0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
32ad0 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  4()] interface r
32ae0 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20  ather than this 
32af0 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44  one..*/.SQLITE_D
32b00 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
32b10 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
32b20 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a  _limit(int N);..
32b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32b40 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
32b50 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
32b60 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a   Of A Table.**.*
32b70 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
32b80 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61  returns metadata
32b90 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
32ba0 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
32bb0 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61  ecific.** databa
32bc0 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  se table accessi
32bd0 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64  ble using the [d
32be0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32bf0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61  on] handle.** pa
32c00 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
32c10 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  t function argum
32c20 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
32c30 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
32c40 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
32c50 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
32c60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
32c70 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  to.** this funct
32c80 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ion. ^The second
32c90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
32ca0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
32cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
32cc0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
32cd0 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74  temp", or an att
32ce0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
32cf0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
32d00 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
32d10 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69  e or NULL. ^If i
32d20 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
32d30 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
32d40 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
32d50 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
32d60 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
32d70 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73  ame algorithm us
32d80 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
32d90 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20  se engine to.** 
32da0 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66  resolve unqualif
32db0 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65  ied table refere
32dc0 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nces..**.** ^The
32dd0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
32de0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
32df0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72  this function ar
32e00 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20  e the table and 
32e10 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f  column.** name o
32e20 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  f the desired co
32e30 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65  lumn, respective
32e40 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74  ly. Neither of t
32e50 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a  hese parameters.
32e60 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a  ** may be NULL..
32e70 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20  **.** ^Metadata 
32e80 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
32e90 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
32ea0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
32eb0 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68  assed as the 5th
32ec0 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65  .** and subseque
32ed0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
32ee0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
32ef0 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72  ^Any of these ar
32f00 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a  guments may be.*
32f10 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  * NULL, in which
32f20 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
32f30 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
32f40 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f  of metadata is o
32f50 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  mitted..**.** ^(
32f60 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
32f70 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
32f80 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50  ">.** <tr><th> P
32f90 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75  arameter <th> Ou
32fa0 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68  tput<br>Type <th
32fb0 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a  >  Description.*
32fc0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74  *.** <tr><td> 5t
32fd0 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61  h <td> const cha
32fe0 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70  r* <td> Data typ
32ff0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74  e.** <tr><td> 6t
33000 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61  h <td> const cha
33010 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20  r* <td> Name of 
33020 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
33030 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74  n sequence.** <t
33040 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20  r><td> 7th <td> 
33050 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
33060 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
33070 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63  has a NOT NULL c
33080 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72  onstraint.** <tr
33090 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69  ><td> 8th <td> i
330a0 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
330b0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
330c0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52  s part of the PR
330d0 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72  IMARY KEY.** <tr
330e0 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69  ><td> 9th <td> i
330f0 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
33100 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
33110 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  s [AUTOINCREMENT
33120 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ].** </table>.**
33130 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
33140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
33150 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ry pointed to by
33160 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70   the character p
33170 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
33180 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c   for the.** decl
33190 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
331a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
331b0 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
331c0 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
331d0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
331e0 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74  SQLite API funct
331f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
33200 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
33210 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
33220 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72   view, an [error
33230 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
33240 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
33250 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
33260 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22  mn is "rowid", "
33270 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f  oid" or "_rowid_
33280 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54  " and an.** [INT
33290 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
332a0 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65  ] column has bee
332b0 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  n explicitly dec
332c0 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20  lared, then the 
332d0 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65  output.** parame
332e0 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72  ters are set for
332f0 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20   the explicitly 
33300 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e  declared column.
33310 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 6e   ^(If there is n
33320 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
33330 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45  declared [INTEGE
33340 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
33350 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
33360 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65  output.** parame
33370 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
33380 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
33390 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61  pre>.**     data
333a0 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22   type: "INTEGER"
333b0 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f  .**     collatio
333c0 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e  n sequence: "BIN
333d0 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20  ARY".**     not 
333e0 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70  null: 0.**     p
333f0 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a  rimary key: 1.**
33400 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d       auto increm
33410 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e  ent: 0.** </pre>
33420 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
33430 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
33440 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
33450 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
33460 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
33470 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
33480 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
33490 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
334a0 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
334b0 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
334c0 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
334d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
334e0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
334f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c   error message l
33500 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64  eft.** in the [d
33510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33520 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69  on] (to be retri
33530 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  eved using sqlit
33540 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a  e3_errmsg()).)^.
33550 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20  **.** ^This API 
33560 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
33570 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
33580 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
33590 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
335a0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
335b0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
335c0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
335d0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
335e0 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
335f0 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
33600 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
33610 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33620 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
33630 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
33640 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
33650 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
33660 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
33670 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
33680 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
33690 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
336a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
336b0 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
336c0 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
336d0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
336e0 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
336f0 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
33700 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
33710 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
33720 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
33730 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
33740 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
33750 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
33760 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
33770 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
33780 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
33790 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
337a0 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
337b0 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
337c0 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
337d0 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
337e0 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
337f0 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
33800 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
33810 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
33820 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
33830 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
33840 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
33850 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  xtension.**.** ^
33860 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c  This interface l
33870 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65  oads an SQLite e
33880 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
33890 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20   from the named 
338a0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  file..**.** ^The
338b0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
338c0 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
338d0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
338e0 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74  load an.** SQLit
338f0 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
33900 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e  ary contained in
33910 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e   the file zFile.
33920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72  .**.** ^The entr
33930 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63  y point is zProc
33940 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20  ..** ^zProc may 
33950 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
33960 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
33970 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
33980 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22  ** defaults to "
33990 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f  sqlite3_extensio
339a0 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65  n_init"..** ^The
339b0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
339c0 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
339d0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ace returns.** [
339e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
339f0 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54  ccess and [SQLIT
33a00 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65  E_ERROR] if some
33a10 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
33a20 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  ..** ^If an erro
33a30 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45  r occurs and pzE
33a40 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20  rrMsg is not 0, 
33a50 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  then the.** [sql
33a60 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
33a70 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
33a80 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74   shall attempt t
33a90 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72  o.** fill *pzErr
33aa0 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d  Msg with error m
33ab0 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
33ac0 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
33ad0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
33ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33af0 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  . The calling fu
33b00 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  nction.** should
33b10 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72   free this memor
33b20 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  y by calling [sq
33b30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
33b40 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
33b50 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
33b60 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
33b70 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
33b80 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
33b90 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  )] prior to call
33ba0 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a  ing this API,.**
33bb0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
33bc0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ror will be retu
33bd0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rned..**.** See 
33be0 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65  also the [load_e
33bf0 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66  xtension() SQL f
33c00 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74  unction]..*/.int
33c10 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
33c20 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
33c30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
33c40 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
33c50 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
33c60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33c70 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
33c80 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
33c90 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
33ca0 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
33cb0 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
33cc0 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
33cd0 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
33ce0 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
33cf0 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
33d00 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
33d10 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
33d20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
33d30 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
33d40 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
33d50 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
33d60 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
33d70 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
33d80 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74  **.** ^So as not
33d90 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
33da0 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
33db0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
33dc0 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
33dd0 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
33de0 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
33df0 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
33e00 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
33e10 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
33e20 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
33e30 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
33e40 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
33e50 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73  lowing API.** is
33e60 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
33e70 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
33e80 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
33e90 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
33ea0 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  d off..**.** ^Ex
33eb0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
33ec0 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
33ed0 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  t. See ticket #1
33ee0 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68  863..** ^Call th
33ef0 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  e sqlite3_enable
33f00 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
33f10 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f  ) routine with o
33f20 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75  noff==1.** to tu
33f30 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  rn extension loa
33f40 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c  ding on and call
33f50 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d   it with onoff==
33f60 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20  0 to turn.** it 
33f70 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a  back off again..
33f80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
33f90 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
33fa0 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
33fb0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
33fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
33fd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
33fe0 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e  d Statically Lin
33ff0 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a  ked Extensions.*
34000 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
34010 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
34020 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75  xEntryPoint() fu
34030 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
34040 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68  oked for.** each
34050 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
34060 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
34070 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65  is created.  The
34080 20 69 64 65 61 20 68 65 72 65 20 69 73 20 74 68   idea here is th
34090 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e  at.** xEntryPoin
340a0 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 79  t() is the entry
340b0 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61   point for a sta
340c0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53  tically linked S
340d0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a  QLite extension.
340e0 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 65  ** that is to be
340f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c   automatically l
34100 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e  oaded into all n
34110 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
34120 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ections..**.** ^
34130 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65  (Even though the
34140 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74   function protot
34150 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 78  ype shows that x
34160 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b  EntryPoint() tak
34170 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e  es.** no argumen
34180 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76  ts and returns v
34190 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f  oid, SQLite invo
341a0 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  kes xEntryPoint(
341b0 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20  ) with three.** 
341c0 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78  arguments and ex
341d0 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65  pects and intege
341e0 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 20 74  r result as if t
341f0 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  he signature of 
34200 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69  the.** entry poi
34210 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c  nt where as foll
34220 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
34230 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
34240 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74  &nbsp;  int xEnt
34250 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73  ryPoint(.** &nbs
34260 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64  p;    sqlite3 *d
34270 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  b,.** &nbsp;    
34280 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45  const char **pzE
34290 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b  rrMsg,.** &nbsp;
342a0 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74      const struct
342b0 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
342c0 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a  tines *pThunk.**
342d0 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c   &nbsp;  );.** <
342e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
342f0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  e>)^.**.** If th
34300 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f  e xEntryPoint ro
34310 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73  utine encounters
34320 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68   an error, it sh
34330 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72  ould make *pzErr
34340 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  Msg.** point to 
34350 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
34360 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62  rror message (ob
34370 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
34380 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29  ite3_mprintf()])
34390 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61  .** and return a
343a0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
343b0 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51  rror code].  ^SQ
343c0 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 68 61  Lite ensures tha
343d0 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69  t *pzErrMsg.** i
343e0 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61  s NULL before ca
343f0 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79  lling the xEntry
34400 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74  Point().  ^SQLit
34410 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  e will invoke.**
34420 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
34430 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61  ] on *pzErrMsg a
34440 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74  fter xEntryPoint
34450 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66  () returns.  ^If
34460 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f   any.** xEntryPo
34470 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e  int() returns an
34480 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c   error, the [sql
34490 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
344a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
344b0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
344c0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c  _open_v2()] call
344d0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
344e0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
344f0 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a   will fail..**.*
34500 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
34510 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34520 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74  n(X) with an ent
34530 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20  ry point X that 
34540 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e  is already.** on
34550 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74   the list of aut
34560 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
34570 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  s is a harmless 
34580 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79  no-op. ^No entry
34590 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62   point.** will b
345a0 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68  e called more th
345b0 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  an once for each
345c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
345d0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65  tion that is ope
345e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ned..**.** See a
345f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65  lso: [sqlite3_re
34600 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
34610 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  on()]..*/.int sq
34620 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
34630 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74  sion(void (*xEnt
34640 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b  ryPoint)(void));
34650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34660 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
34670 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
34680 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ing.**.** ^This 
34690 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 62 6c  interface disabl
346a0 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63  es all automatic
346b0 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 76   extensions prev
346c0 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74  iously.** regist
346d0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
346e0 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
346f0 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73  on()]..*/.void s
34700 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
34710 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
34720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
34730 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
34740 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
34750 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
34760 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
34770 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
34780 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
34790 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
347a0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
347b0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
347c0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
347d0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
347e0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
347f0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
34800 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
34810 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
34820 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
34830 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
34840 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
34850 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
34860 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
34870 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
34880 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
34890 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
348a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
348b0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
348c0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
348d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
348e0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
348f0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
34900 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
34910 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
34920 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
34930 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
34940 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
34950 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
34960 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
34970 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
34980 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
34990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
349a0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
349b0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
349c0 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
349d0 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
349e0 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  module}.**.** Th
349f0 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f  is structure, so
34a00 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61  metimes called a
34a10 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
34a20 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
34a30 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
34a40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
34a50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
34a60 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
34a70 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
34a80 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
34a90 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
34aa0 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
34ab0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
34ac0 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
34ad0 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
34ae0 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
34af0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
34b00 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
34b10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
34b20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
34b30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
34b40 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
34b50 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
34b60 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
34b70 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
34b80 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
34b90 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
34ba0 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
34bb0 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
34bc0 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
34bd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
34be0 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
34bf0 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
34c00 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
34c10 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
34c20 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
34c30 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
34c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
34c50 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
34c60 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
34c70 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
34c80 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
34c90 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
34ca0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34cb0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
34cc0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
34cd0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
34ce0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
34cf0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
34d00 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
34d10 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
34d20 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
34d30 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
34d40 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
34d50 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
34d60 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
34d70 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
34d80 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
34d90 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
34da0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34db0 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
34dc0 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
34dd0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
34de0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34df0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
34e00 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
34e10 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34e20 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
34e30 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
34e40 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34e50 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
34e60 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
34e70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
34e80 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
34e90 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
34ea0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
34eb0 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
34ec0 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
34ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
34ee0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
34ef0 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
34f00 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
34f10 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34f20 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
34f30 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
34f40 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
34f50 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
34f60 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
34f70 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
34f80 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
34f90 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
34fa0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
34fb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
34fc0 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
34fd0 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
34fe0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
34ff0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
35000 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
35010 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
35020 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35030 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35040 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
35050 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
35060 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
35070 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35080 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
35090 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
350a0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
350b0 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
350c0 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
350d0 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
350e0 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
350f0 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
35100 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
35110 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
35120 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35130 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35140 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
35150 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
35160 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
35170 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
35180 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
35190 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
351a0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
351b0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
351c0 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e  able Indexing In
351d0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59  formation.** KEY
351e0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
351f0 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20  ndex_info.**.** 
35200 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
35210 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
35220 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
35230 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 61  ctures is used a
35240 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65  s part.** of the
35250 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
35260 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
35270 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f   pass informatio
35280 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69  n into and recei
35290 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f  ve the reply fro
352a0 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65  m the [xBestInde
352b0 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  x].** method of 
352c0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
352d0 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66   module].  The f
352e0 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
352f0 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
35300 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
35310 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
35320 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
35330 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
35340 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
35350 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
35360 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
35370 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  ^(The aConstrain
35380 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64  t[] array record
35390 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  s WHERE clause c
353a0 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68  onstraints of th
353b0 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e form:.**.** <b
353c0 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e  lockquote>column
353d0 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71   OP expr</blockq
353e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72  uote>.**.** wher
353f0 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
35400 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
35410 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65   &gt;=.)^  ^(The
35420 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
35430 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
35440 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
35450 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20  [].op using one 
35460 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  of the.** [SQLIT
35470 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
35480 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49  NT_EQ | SQLITE_I
35490 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
354a0 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e   values].)^.** ^
354b0 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68  (The index of th
354c0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72  e column is stor
354d0 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72  ed in.** aConstr
354e0 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29  aint[].iColumn.)
354f0 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74  ^  ^(aConstraint
35500 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55  [].usable is TRU
35510 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72  E if the.** expr
35520 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61   on the right-ha
35530 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65  nd side can be e
35540 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68  valuated (and th
35550 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  us the constrain
35560 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20  t.** is usable) 
35570 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20  and false if it 
35580 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cannot.)^.**.** 
35590 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61  ^The optimizer a
355a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
355b0 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
355c0 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
355d0 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
355e0 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
355f0 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
35600 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
35610 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
35620 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
35630 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
35640 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
35650 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
35660 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65  ossible..** ^The
35670 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
35680 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
35690 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
356a0 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  erms that are.**
356b0 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65   relevant to the
356c0 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
356d0 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20  ual table being 
356e0 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  queried..**.** ^
356f0 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  Information abou
35700 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  t the ORDER BY c
35710 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20  lause is stored 
35720 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a  in aOrderBy[]..*
35730 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20  * ^Each term of 
35740 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
35750 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
35760 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35770 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65  ..**.** The [xBe
35780 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20  stIndex] method 
35790 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
357a0 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
357b0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
357c0 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
357d0 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
357e0 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20  o xFilter.  ^If 
357f0 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
35800 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
35810 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
35820 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
35830 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
35840 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
35850 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
35860 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
35870 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f   argv.  ^(If aCo
35880 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
35890 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
358a0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
358b0 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
358c0 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
358d0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
358e0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
358f0 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
35900 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29  gain by SQLite.)
35910 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78  ^.**.** ^The idx
35920 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
35930 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
35940 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
35950 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74  to the.** [xFilt
35960 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e  er] method..** ^
35970 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
35980 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
35990 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f   idxPtr if and o
359a0 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f  nly if.** needTo
359b0 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
359c0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  ue..**.** ^The o
359d0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
359e0 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
359f0 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f   from [xFilter]/
35a00 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63  [xNext] will occ
35a10 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
35a20 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
35a30 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
35a40 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
35a50 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
35a60 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
35a70 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
35a80 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43   ^The estimatedC
35a90 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20  ost value is an 
35aa0 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20  estimate of the 
35ab0 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68  cost of doing th
35ac0 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20  e.** particular 
35ad0 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20  lookup.  A full 
35ae0 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20  scan of a table 
35af0 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73  with N entries s
35b00 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20  hould have.** a 
35b10 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69  cost of N.  A bi
35b20 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61  nary search of a
35b30 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72   table of N entr
35b40 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20  ies should have 
35b50 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70  a.** cost of app
35b60 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e  roximately log(N
35b70 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
35b80 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
35b90 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f  {.  /* Inputs */
35ba0 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69  .  int nConstrai
35bb0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  nt;           /*
35bc0 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69   Number of entri
35bd0 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  es in aConstrain
35be0 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  t */.  struct sq
35bf0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
35c00 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e  traint {.     in
35c10 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
35c20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
35c30 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73  n on left-hand s
35c40 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e  ide of constrain
35c50 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  t */.     unsign
35c60 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20  ed char op;     
35c70 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e      /* Constrain
35c80 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20  t operator */.  
35c90 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
35ca0 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20   usable;     /* 
35cb0 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e  True if this con
35cc0 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c  straint is usabl
35cd0 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54  e */.     int iT
35ce0 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20  ermOffset;      
35cf0 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
35d00 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e  rnally - xBestIn
35d10 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72  dex should ignor
35d20 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  e */.  } *aConst
35d30 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
35d40 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48    /* Table of WH
35d50 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
35d60 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20  raints */.  int 
35d70 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  nOrderBy;       
35d80 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
35d90 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65   of terms in the
35da0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35db0 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
35dc0 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
35dd0 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  by {.     int iC
35de0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
35df0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
35e00 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  mber */.     uns
35e10 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b  igned char desc;
35e20 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66         /* True f
35e30 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20  or DESC.  False 
35e40 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20  for ASC. */.  } 
35e50 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20  *aOrderBy;      
35e60 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20           /* The 
35e70 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
35e80 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20  */.  /* Outputs 
35e90 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
35ea0 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
35eb0 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20  aint_usage {.   
35ec0 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
35ed0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
35ee0 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
35ef0 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
35f00 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20  o xFilter */.   
35f10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
35f20 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20  mit;      /* Do 
35f30 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20  not code a test 
35f40 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61  for this constra
35f50 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  int */.  } *aCon
35f60 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20  straintUsage;.  
35f70 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20  int idxNum;     
35f80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
35f90 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65  mber used to ide
35fa0 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20  ntify the index 
35fb0 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74  */.  char *idxSt
35fc0 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  r;              
35fd0 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
35fe0 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
35ff0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
36000 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f   */.  int needTo
36010 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20  FreeIdxStr;     
36020 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20   /* Free idxStr 
36030 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  using sqlite3_fr
36040 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a  ee() if true */.
36050 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e    int orderByCon
36060 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20  sumed;       /* 
36070 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69  True if output i
36080 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65  s already ordere
36090 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73  d */.  double es
360a0 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20  timatedCost;    
360b0 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63    /* Estimated c
360c0 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ost of using thi
360d0 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f  s index */.};../
360e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
360f0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e  irtual Table Con
36100 73 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72  straint Operator
36110 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
36120 73 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65  se macros define
36130 64 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61  d the allowed va
36140 6c 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lues for the.** 
36150 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69  [sqlite3_index_i
36160 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74  nfo].aConstraint
36170 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61  [].op field.  Ea
36180 63 68 20 76 61 6c 75 65 20 72 65 70 72 65 73 65  ch value represe
36190 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74  nts.** an operat
361a0 6f 72 20 74 68 61 74 20 69 73 20 70 61 72 74 20  or that is part 
361b0 6f 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  of a constraint 
361c0 74 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52  term in the wHER
361d0 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61  E clause of.** a
361e0 20 71 75 65 72 79 20 74 68 61 74 20 75 73 65 73   query that uses
361f0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
36200 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e]..*/.#define S
36210 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36220 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
36230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
36240 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
36250 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
36260 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36270 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
36280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
36290 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
362a0 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
362b0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
362c0 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
362d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
362e0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
362f0 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
36300 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
36310 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
36320 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
36330 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
36340 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
36350 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
36360 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
36370 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e  le module] name.
36380 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65  .** ^Module name
36390 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
363a0 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
363b0 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
363c0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
363d0 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ing the module a
363e0 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  nd before using 
363f0 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
36400 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
36410 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
36420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75  .**.** ^The modu
36430 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73  le name is regis
36440 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61  tered on the [da
36450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36460 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  n] specified.** 
36470 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
36480 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61  ameter.  ^The na
36490 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
364a0 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
364b0 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61   .** second para
364c0 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69  meter.  ^The thi
364d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
364e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
364f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
36500 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
36510 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
36520 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a  .   ^The fourth.
36530 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
36540 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69  an arbitrary cli
36550 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ent data pointer
36560 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
36570 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20  through.** into 
36580 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
36590 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
365a0 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74  hods of the virt
365b0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
365c0 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76  .** when a new v
365d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
365e0 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  be being created
365f0 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65   or reinitialize
36600 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
36610 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36620 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ule_v2() interfa
36630 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70  ce has a fifth p
36640 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
36650 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
36660 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
36670 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  or the pClientDa
36680 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ta.  ^SQLite wil
36690 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  l.** invoke the 
366a0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
366b0 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f  ion (if it is no
366c0 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c  t NULL) when SQL
366d0 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72  ite.** no longer
366e0 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65   needs the pClie
366f0 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  ntData pointer. 
36700 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
36710 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65   will also.** be
36720 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
36730 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36740 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
36750 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68  () fails..** ^Th
36760 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36770 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74  _module().** int
36780 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
36790 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  lent to sqlite3_
367a0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
367b0 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a  () with a NULL.*
367c0 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f  * destructor..*/
367d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
367e0 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
367f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36800 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
36810 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
36820 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
36830 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
36840 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
36850 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
36860 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
36870 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
36880 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
36890 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
368a0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
368b0 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
368c0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
368d0 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
368e0 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
368f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36900 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
36910 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36920 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
36930 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
36940 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
36950 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
36960 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
36970 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
36980 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
36990 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
369a0 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
369b0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
369c0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
369d0 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20  d *pClientData, 
369e0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
369f0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
36a00 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
36a10 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
36a20 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
36a30 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
36a40 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
36a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36a60 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
36a70 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a  nstance Object.*
36a80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
36a90 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45  te3_vtab.**.** E
36aa0 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
36ab0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
36ac0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
36ad0 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66  a subclass.** of
36ae0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20   this object to 
36af0 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69  describe a parti
36b00 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a  cular instance.*
36b10 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
36b20 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20  l table].  Each 
36b30 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
36b40 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
36b50 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
36b60 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
36b70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
36b80 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20  .** The purpose 
36b90 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
36ba0 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
36bb0 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
36bc0 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f  hat are.** commo
36bd0 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  n to all module 
36be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
36bf0 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20  .**.** ^Virtual 
36c00 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63  tables methods c
36c10 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20  an set an error 
36c20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67  message by assig
36c30 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67  ning a.** string
36c40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36c50 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
36c60 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  )] to zErrMsg.  
36c70 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
36c80 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
36c90 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
36ca0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
36cb0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
36cc0 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70  te3_free()].** p
36cd0 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
36ce0 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
36cf0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74  o zErrMsg.  ^Aft
36d00 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
36d10 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76  sage.** is deliv
36d20 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63  ered up to the c
36d30 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  lient applicatio
36d40 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  n, the string wi
36d50 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
36d60 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20  lly.** freed by 
36d70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
36d80 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66  nd the zErrMsg f
36d90 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72  ield will be zer
36da0 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  oed..*/.struct s
36db0 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
36dc0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
36dd0 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
36de0 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
36df0 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
36e00 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
36e10 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
36e20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20            /* NO 
36e30 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20  LONGER USED */. 
36e40 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
36e50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e60 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
36e70 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
36e80 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
36e90 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
36ea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
36eb0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
36ec0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
36ed0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
36ee0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
36ef0 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
36f00 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
36f10 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
36f20 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c  _cursor {virtual
36f30 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a   table cursor}.*
36f40 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
36f50 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
36f60 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
36f70 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
36f80 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f   of the.** follo
36f90 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74  wing structure t
36fa0 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f  o describe curso
36fb0 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e  rs that point in
36fc0 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75  to the.** [virtu
36fd0 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72  al table] and ar
36fe0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f  e used.** to loo
36ff0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69  p through the vi
37000 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75  rtual table.  Cu
37010 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65  rsors are create
37020 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
37030 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
37040 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65  Open | xOpen] me
37050 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75  thod of the modu
37060 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72  le and are destr
37070 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  oyed.** by the [
37080 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
37090 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20  Close | xClose] 
370a0 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73  method.  Cursors
370b0 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20   are used.** by 
370c0 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b  the [xFilter], [
370d0 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20  xNext], [xEof], 
370e0 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b  [xColumn], and [
370f0 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a  xRowid] methods.
37100 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ** of the module
37110 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
37120 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
37130 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
37140 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
37150 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
37160 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
37170 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
37180 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
37190 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
371a0 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
371b0 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
371c0 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
371d0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
371e0 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
371f0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37200 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
37210 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
37220 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
37230 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
37240 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
37250 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37260 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37270 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37280 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37290 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
372a0 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20  EF: Declare The 
372b0 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74  Schema Of A Virt
372c0 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
372d0 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61  ^The [xCreate] a
372e0 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
372f0 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76  thods of a.** [v
37300 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
37310 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69  ule] call this i
37320 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64  nterface.** to d
37330 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
37340 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
37350 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
37360 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
37370 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
37380 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
37390 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
373a0 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
373b0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
373c0 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a  char *zSQL);../*
373d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76  .** CAPI3REF: Ov
373e0 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f  erload A Functio
373f0 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20  n For A Virtual 
37400 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69  Table.**.** ^(Vi
37410 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
37420 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61   provide alterna
37430 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tive implementat
37440 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e  ions of function
37450 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  s.** using the [
37460 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d  xFindFunction] m
37470 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69  ethod of the [vi
37480 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
37490 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c  le].  .** But gl
374a0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
374b0 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
374c0 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
374d0 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
374e0 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a  erloaded.)^.**.*
374f0 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b  * ^(This API mak
37500 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
37510 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
37520 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
37530 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
37540 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
37550 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
37560 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
37570 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
37580 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
37590 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
375a0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
375b0 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69  eated.)^  ^The i
375c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
375d0 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63   of the new func
375e0 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73  tion always caus
375f0 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  es an exception 
37600 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53  to be thrown.  S
37610 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e  o.** the new fun
37620 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f  ction is not goo
37630 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62  d for anything b
37640 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f  y itself.  Its o
37650 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69  nly.** purpose i
37660 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68  s to be a placeh
37670 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
37680 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
37690 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76  oaded.** by a [v
376a0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a  irtual table]..*
376b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  /.int sqlite3_ov
376c0 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
376d0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
376e0 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
376f0 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
37700 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
37710 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
37720 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
37730 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
37740 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
37750 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
37760 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
37770 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
37780 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
37790 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
377a0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
377b0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
377c0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
377d0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
377e0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
377f0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
37800 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
37810 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
37820 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
37830 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
37840 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
37850 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
37860 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
37870 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
37880 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
37890 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
378a0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
378b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
378c0 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
378d0 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59  Open BLOB.** KEY
378e0 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
378f0 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
37900 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
37910 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
37920 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
37930 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
37940 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
37950 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
37960 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
37970 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
37980 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74  rmed..** ^Object
37990 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61  s of this type a
379a0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  re created by [s
379b0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
379c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72  ()].** and destr
379d0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
379e0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
379f0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
37a00 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
37a10 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
37a20 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
37a30 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
37a40 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
37a50 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
37a60 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f  tions of the BLO
37a70 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  B..** ^The [sqli
37a80 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
37a90 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
37aa0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
37ab0 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65  the BLOB in byte
37ac0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
37ad0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
37ae0 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
37af0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37b00 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
37b10 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
37b20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
37b30 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61  terfaces opens a
37b40 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20   [BLOB handle | 
37b50 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42  handle] to the B
37b60 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69  LOB located.** i
37b70 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75  n row iRow, colu
37b80 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c  mn zColumn, tabl
37b90 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61  e zTable in data
37ba0 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20  base zDb;.** in 
37bb0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
37bc0 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20   same BLOB that 
37bd0 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65  would be selecte
37be0 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
37bf0 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
37c00 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
37c10 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72  .zTable WHERE [r
37c20 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a  owid] = iRow;.**
37c30 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
37c40 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61  ^If the flags pa
37c50 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
37c60 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c  ero, then the BL
37c70 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
37c80 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69   read.** and wri
37c90 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69  te access. ^If i
37ca0 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42  t is zero, the B
37cb0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
37cc0 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a  r read access..*
37cd0 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73  * ^It is not pos
37ce0 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
37cf0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
37d00 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20  art of an index 
37d10 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b  or primary .** k
37d20 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20  ey for writing. 
37d30 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  ^If [foreign key
37d40 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72   constraints] ar
37d50 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73  e enabled, it is
37d60 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c   .** not possibl
37d70 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75  e to open a colu
37d80 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20  mn that is part 
37d90 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d  of a [child key]
37da0 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a   for writing..**
37db0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
37dc0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
37dd0 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   is not the file
37de0 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69  name that contai
37df0 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
37e00 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68  se but rather th
37e10 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
37e20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37e30 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20  that.** appears 
37e40 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79  after the AS key
37e50 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61  word when the da
37e60 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63  tabase is connec
37e70 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43  ted using [ATTAC
37e80 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  H]..** ^For the 
37e90 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
37ea0 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  le, the database
37eb0 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e   name is "main".
37ec0 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61  .** ^For TEMP ta
37ed0 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61  bles, the databa
37ee0 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70  se name is "temp
37ef0 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75  "..**.** ^(On su
37f00 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
37f10 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  K] is returned a
37f20 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42  nd the new [BLOB
37f30 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74   handle] is writ
37f40 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f  ten.** to *ppBlo
37f50 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  b. Otherwise an 
37f60 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
37f70 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70  returned and *pp
37f80 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74  Blob is set.** t
37f90 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  o be a null poin
37fa0 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20  ter.)^.** ^This 
37fb0 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
37fc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37fd0 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f  ection] error co
37fe0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
37ff0 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
38000 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
38010 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
38020 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
38030 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74  related.** funct
38040 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74  ions. ^Note that
38050 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72   the *ppBlob var
38060 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20  iable is always 
38070 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61  initialized in a
38080 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b  .** way that mak
38090 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e  es it safe to in
380a0 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c  voke [sqlite3_bl
380b0 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a  ob_close()] on *
380c0 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64  ppBlob.** regard
380d0 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
380e0 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  ess or failure o
380f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
38100 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72  **.** ^(If the r
38110 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
38120 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
38130 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
38140 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
38150 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
38160 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
38170 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
38180 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
38190 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
381a0 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
381b0 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
381c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
381d0 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
381e0 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
381f0 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
38200 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
38210 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e  le is open on.)^
38220 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73  .** ^Calls to [s
38230 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
38240 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
38250 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66  _blob_write()] f
38260 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20  or.** a expired 
38270 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c  BLOB handle fail
38280 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20   with an return 
38290 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
382a0 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61  ABORT]..** ^(Cha
382b0 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74  nges written int
382c0 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74  o a BLOB prior t
382d0 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72  o the BLOB expir
382e0 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  ing are not.** r
382f0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
38300 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  e expiration of 
38310 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20  the BLOB.  Such 
38320 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65  changes will eve
38330 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69  ntually.** commi
38340 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63  t if the transac
38350 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74  tion continues t
38360 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a  o completion.)^.
38370 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b  **.** ^Use the [
38380 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
38390 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
383a0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
383b0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
383c0 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54  opened blob.  ^T
383d0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
383e0 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61  b may not be cha
383f0 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  nged by this.** 
38400 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20  interface.  Use 
38410 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c  the [UPDATE] SQL
38420 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e   command to chan
38430 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
38440 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  .** blob..**.** 
38450 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69  ^The [sqlite3_bi
38460 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61  nd_zeroblob()] a
38470 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
38480 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69  lt_zeroblob()] i
38490 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64  nterfaces.** and
384a0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a   the built-in [z
384b0 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e  eroblob] SQL fun
384c0 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ction can be use
384d0 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a  d, if desired,.*
384e0 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65  * to create an e
384f0 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65  mpty, zero-fille
38500 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20  d blob in which 
38510 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  to read or write
38520 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69   using.** this i
38530 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
38540 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75  To avoid a resou
38550 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20  rce leak, every 
38560 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
38570 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75  e] should eventu
38580 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61  ally.** be relea
38590 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  sed by a call to
385a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
385b0 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  lose()]..*/.int 
385c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
385d0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
385e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
385f0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
38600 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
38610 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
38620 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
38630 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
38640 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
38650 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
38660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 6f  .** CAPI3REF: Mo
38670 76 65 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65  ve a BLOB Handle
38680 20 74 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a   to a New Row.**
38690 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
386a0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 6d 6f  on is used to mo
386b0 76 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62  ve an existing b
386c0 6c 6f 62 20 68 61 6e 64 6c 65 20 73 6f 20 74 68  lob handle so th
386d0 61 74 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20  at it points.** 
386e0 74 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20 72  to a different r
386f0 6f 77 20 6f 66 20 74 68 65 20 73 61 6d 65 20 64  ow of the same d
38700 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 5e  atabase table. ^
38710 54 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20 69  The new row is i
38720 64 65 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79 20  dentified.** by 
38730 74 68 65 20 72 6f 77 69 64 20 76 61 6c 75 65 20  the rowid value 
38740 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
38750 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f  cond argument. O
38760 6e 6c 79 20 74 68 65 20 72 6f 77 20 63 61 6e 20  nly the row can 
38770 62 65 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20 5e  be.** changed. ^
38780 54 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  The database, ta
38790 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f  ble and column o
387a0 6e 20 77 68 69 63 68 20 74 68 65 20 62 6c 6f 62  n which the blob
387b0 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 0a   handle is open.
387c0 2a 2a 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61  ** remain the sa
387d0 6d 65 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65 78  me. Moving an ex
387e0 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64  isting blob hand
387f0 6c 65 20 74 6f 20 61 20 6e 65 77 20 72 6f 77 20  le to a new row 
38800 63 61 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65 72  can be.** faster
38810 20 74 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74 68   than closing th
38820 65 20 65 78 69 73 74 69 6e 67 20 68 61 6e 64 6c  e existing handl
38830 65 20 61 6e 64 20 6f 70 65 6e 69 6e 67 20 61 20  e and opening a 
38840 6e 65 77 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e  new one..**.** ^
38850 28 54 68 65 20 6e 65 77 20 72 6f 77 20 6d 75 73  (The new row mus
38860 74 20 6d 65 65 74 20 74 68 65 20 73 61 6d 65 20  t meet the same 
38870 63 72 69 74 65 72 69 61 20 61 73 20 66 6f 72 20  criteria as for 
38880 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
38890 65 6e 28 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d 75  e