/ Hex Artifact Content
Login

Artifact 46c01e55cea31b91565ae41276c6310ee4032be8:


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 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
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: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5630: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5640: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5650: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
5660: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
5670: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5690: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
56a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
56b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
56c0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
56d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
56e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
56f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5700: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5710: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5720: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5730: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5740: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5750: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5770: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5780: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5790: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
57a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
57b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
57d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
57e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
57f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5800: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5810: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5820: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5830: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5840: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5850: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5870: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5880: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5890: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
58a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
58b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
58c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
58d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
58e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
58f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5900: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5920: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5930: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5940: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5950: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5960: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5970: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5980: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
59a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
59b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
59c0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
59d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
59e0: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
59f0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5a00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5a10: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a20: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5a40: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a50: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5a60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5a70: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5a80: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
5a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5aa0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5ab0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
5ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5ad0: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
5ae0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5b00: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
5b10: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
5b20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
5b30: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
5b40: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
5b50: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5b60: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
5b70: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
5b80: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b90: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
5ba0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
5bb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5bc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5bd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5be0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5bf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5c00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5c10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5c20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5c30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5c40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5c50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5c60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5c90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5ca0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5cb0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5cc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5cd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5cf0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5d20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5d30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5d40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5d50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5d60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5d70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5d80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5d90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5da0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5db0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5dc0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5dd0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5de0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5df0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5e00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5e10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5e20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5e30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5e40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5e50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5e60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5e70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5e80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5e90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5ea0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5eb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5ec0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5ed0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5ee0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ef0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5f00: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
5f10: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
5f20: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
5f30: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
5f40: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
5f50: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
5f60: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
5f70: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
5f80: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
5f90: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
5fa0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
5fb0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
5fc0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
5fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5fe0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
5ff0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
6000: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6010: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
6020: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
6030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6040: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6050: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6060: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
6070: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
6080: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
6090: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
60a0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
60b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
60c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
60d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
60e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
60f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6100: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6110: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6120: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6130: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6150: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
6160: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
6170: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
6180: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
6190: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
61a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
61b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
61c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
61d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
61e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
61f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6200: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6210: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6220: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6230: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6240: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6250: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
6260: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
6270: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
6280: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
6290: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
62a0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
62b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
62c0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
62d0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
62e0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
62f0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6300: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
6310: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
6320: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
6330: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
6340: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
6350: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
6360: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
6370: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
6380: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
6390: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
63a0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
63b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63c0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
63d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65   xOpen method se
63e0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
63f0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6400: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
6410: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
6420: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
6430: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
6440: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
6450: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
6460: 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65   if the xOpen re
6470: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
6480: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
6490: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
64a0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
64b0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
64c0: 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20  failed xOpen.** 
64d0: 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e  is for the xOpen
64e0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
64f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6500: 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c  s element to NUL
6510: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
6520: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
6530: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
6540: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
6550: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
6560: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
6570: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
6580: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
6590: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
65a0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
65b0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
65c0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
65d0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
65e0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
65f0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
6600: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
6610: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
6620: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
6630: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
6640: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
6650: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
6660: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
6670: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6680: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
6690: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
66a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
66b0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
66c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
66d0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
66e0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
66f0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6700: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6710: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
6720: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6730: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
6740: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
6750: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
6760: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
6770: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
6780: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
6790: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
67a0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
67b0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
67c0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
67d0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
67e0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
67f0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
6800: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
6810: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
6820: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
6830: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
6840: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
6850: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
6860: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
6870: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
6880: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
6890: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
68a0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
68b0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
68c0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
68d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
68e0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
68f0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
6900: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
6910: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6920: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
6930: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
6940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
6950: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
6960: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
6970: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6980: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
6990: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
69a0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
69b0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
69c0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
69d0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
69e0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
69f0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6a00: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6a10: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6a20: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6a30: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6a40: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6a50: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6a60: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6a70: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
6a80: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
6a90: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
6aa0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
6ab0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
6ac0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
6ad0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6ae0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6af0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6b00: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
6b10: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
6b20: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
6b30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6b40: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
6b50: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
6b60: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
6b70: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
6b80: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
6b90: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
6ba0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
6bb0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
6bc0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
6bd0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
6be0: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
6bf0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
6c00: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
6c10: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
6c20: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
6c30: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
6c40: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
6c50: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
6c60: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
6c70: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
6c80: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
6c90: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
6ca0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
6cb0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
6cc0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6cd0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
6ce0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
6cf0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
6d00: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
6d10: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
6d20: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
6d30: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6d40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6d70: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
6d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6d90: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6da0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6db0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6dd0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6de0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
6df0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6e00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6e10: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
6e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e30: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
6e40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e50: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
6e60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6e70: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
6e80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
6e90: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
6ea0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
6eb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ec0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6ed0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6ee0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6ef0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f10: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
6f20: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6f30: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6f40: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6f50: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6f60: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6f70: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6f80: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6f90: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6fa0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6fb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6fc0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6fd0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6fe0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6ff0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
7000: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
7010: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
7020: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
7030: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
7040: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
7050: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
7060: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
7070: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
7080: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7090: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
70a0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
70b0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
70c0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
70d0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
70e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
70f0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
7100: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
7110: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
7120: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
7130: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
7140: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
7150: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
7160: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
7170: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
7180: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
7190: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
71a0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
71b0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
71c0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
71d0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
71e0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
71f0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
7200: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7210: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
7220: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
7230: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7240: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
7250: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
7260: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
7270: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7280: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7290: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
72a0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
72b0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
72c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
72d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
72e0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
72f0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
7300: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
7310: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
7320: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7330: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
7340: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
7350: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
7360: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
7370: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
7380: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7390: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
73a0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
73b0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
73c0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
73d0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
73e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
73f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
7400: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
7410: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7420: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
7430: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
7440: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7450: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
7460: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
7470: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
7480: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7490: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
74a0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
74b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
74c0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
74d0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
74e0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
74f0: 2a 78 53 68 6d 4f 70 65 6e 29 28 73 71 6c 69 74  *xShmOpen)(sqlit
7500: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7510: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
7520: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7530: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
7540: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
7550: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7560: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7570: 50 61 67 65 2c 20 69 6e 74 20 70 67 73 7a 2c 20  Page, int pgsz, 
7580: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
7590: 6c 65 2a 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  le**);.  void (*
75a0: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
75b0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
75c0: 6e 74 20 28 2a 78 53 68 6d 43 6c 6f 73 65 29 28  nt (*xShmClose)(
75d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
75e0: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
75f0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
7600: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
7610: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
7620: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
7630: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
7640: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
7650: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
7660: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
7670: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
7680: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
7690: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
76a0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
76b0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
76c0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
76d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
76e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
76f0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7710: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7720: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7730: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
7740: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
7750: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
7760: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
7770: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
7780: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
7790: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
77a0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
77b0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
77c0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
77d0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
77e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
77f0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
7800: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
7810: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7820: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
7830: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7840: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
7850: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
7860: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
7870: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
7880: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
7890: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
78a0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
78b0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
78c0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
78d0: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
78e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
78f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
7900: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
7910: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
7920: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
7930: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
7940: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
7950: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
7960: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
7970: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
7980: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
7990: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
79a0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
79b0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
79c0: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
79d0: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
79e0: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
79f0: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
7a00: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
7a10: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
7a20: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
7a30: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
7a40: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
7a50: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
7a60: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2f 0a 23  run faster..*/.#
7a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7a80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
7a90: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
7aa0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
7ab0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
7ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
7ad0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
7ae0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
7af0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
7b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
7b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7b20: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
7b30: 20 20 20 20 20 35 0a 0a 2f 2a 0a 2a 2a 20 43 41       5../*.** CA
7b40: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
7b50: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
7b60: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
7b70: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
7b80: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
7b90: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
7ba0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
7bb0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
7bc0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
7bd0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
7be0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
7bf0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
7c00: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
7c10: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
7c20: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
7c30: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
7c40: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
7c50: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
7c60: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
7c70: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
7c80: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
7c90: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7ca0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
7cb0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
7cc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7cd0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
7ce0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
7cf0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
7d00: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
7d10: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
7d20: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
7d30: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
7d40: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
7d50: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
7d60: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
7d70: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
7d80: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
7d90: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
7da0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
7db0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
7dc0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
7dd0: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
7de0: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
7df0: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
7e00: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
7e10: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
7e20: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
7e30: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
7e40: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
7e50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
7e60: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
7e70: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
7e80: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
7e90: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7ea0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
7eb0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
7ec0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
7ed0: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
7ee0: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
7ef0: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
7f00: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
7f10: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
7f20: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
7f30: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
7f40: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
7f50: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
7f60: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
7f70: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
7f80: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
7f90: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
7fa0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
7fb0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
7fc0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
7fd0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
7fe0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
7ff0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
8000: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
8010: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
8020: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
8030: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
8040: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
8050: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
8060: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
8070: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
8080: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
8090: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
80a0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
80b0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
80c0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
80d0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
80e0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
80f0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
8100: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
8110: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
8120: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
8130: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
8140: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
8150: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
8160: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
8170: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
8180: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
8190: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
81a0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
81b0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
81c0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
81d0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
81e0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
81f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
8200: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
8210: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
8220: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
8230: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
8240: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
8250: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
8260: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
8270: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
8280: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
8290: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
82a0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
82b0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
82c0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
82d0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
82e0: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
82f0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
8300: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
8310: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
8320: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
8330: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
8340: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
8350: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72  e().  SQLite fur
8360: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
8370: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
8380: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
8390: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
83a0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
83b0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
83c0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
83d0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
83e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
83f0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
8400: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
8410: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
8420: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
8430: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
8440: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
8450: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
8460: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8470: 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69  meter is xOpen i
8480: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
8490: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
84a0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
84b0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
84c0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
84d0: 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a   Whenever the .*
84e0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
84f0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
8500: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
8510: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
8520: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
8530: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
8540: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8550: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
8560: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
8570: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
8580: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
8590: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
85a0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
85b0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
85c0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
85d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
85e0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
85f0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
8600: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
8610: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
8620: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
8630: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
8640: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8650: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
8660: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
8670: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
8680: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
8690: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
86a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
86b0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
86c0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
86d0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
86e0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
86f0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8700: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
8710: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
8720: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
8730: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
8740: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
8750: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
8760: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8770: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
8780: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8790: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
87a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
87b0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
87c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87d0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
87e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
87f0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
8800: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8810: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
8820: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8830: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
8840: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
8850: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8860: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
8870: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
8880: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
8890: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
88a0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
88b0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
88c0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
88d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
88e0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
88f0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
8900: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
8910: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
8920: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
8930: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
8940: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
8950: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
8960: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
8970: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
8980: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
8990: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
89a0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
89b0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
89c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
89d0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
89e0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
89f0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
8a00: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
8a10: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
8a20: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
8a30: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
8a40: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
8a50: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
8a60: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
8a70: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
8a80: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8a90: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
8aa0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
8ab0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
8ac0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8ad0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8ae0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
8af0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8b00: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
8b10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8b20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8b30: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
8b40: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8b50: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
8b60: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
8b70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8b80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8b90: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8ba0: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8bb0: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8bc0: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8bd0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  s..**.** The [SQ
8be0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8bf0: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
8c00: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
8c10: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
8c20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
8c30: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
8c40: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
8c50: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
8c60: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
8c70: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
8c80: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
8c90: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
8ca0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
8cb0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
8cc0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
8cd0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
8ce0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
8cf0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
8d00: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
8d10: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
8d20: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
8d30: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
8d40: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
8d50: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
8d60: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
8d70: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
8d80: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
8d90: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
8da0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
8db0: 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73  **.** At least s
8dc0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8dd0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8de0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
8df0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
8e00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
8e10: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
8e20: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
8e30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
8e40: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
8e50: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
8e60: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
8e70: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
8e80: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
8e90: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
8ea0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
8eb0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
8ec0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
8ed0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
8ee0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
8ef0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
8f00: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
8f10: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
8f20: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
8f30: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
8f40: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
8f50: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
8f60: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
8f70: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
8f80: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
8f90: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
8fa0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
8fb0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
8fc0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
8fd0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
8fe0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
8ff0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
9000: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
9010: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9020: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
9030: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
9040: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
9050: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
9060: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
9070: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
9080: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
9090: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
90a0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
90b0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
90c0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
90d0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
90e0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
90f0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
9100: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  ectory..**.** SQ
9110: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
9120: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
9130: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
9140: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
9150: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
9160: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
9170: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
9180: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
9190: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
91a0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
91b0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
91c0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
91d0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
91e0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
91f0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
9200: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
9210: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
9220: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
9230: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
9240: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
9250: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
9260: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
9270: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
9280: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
9290: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
92a0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
92b0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
92c0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
92d0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
92e0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
92f0: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
9300: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9310: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9320: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9330: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9340: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9350: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9360: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
9370: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
9380: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
9390: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
93a0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
93b0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
93c0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
93d0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
93e0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
93f0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
9400: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
9410: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
9420: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
9430: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
9440: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
9450: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
9460: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
9470: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
9480: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72  given.  The xCur
9490: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
94a0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
94b0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
94c0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
94d0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a   date and time..
94e0: 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  **.*/.typedef st
94f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
9500: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74   sqlite3_vfs;.st
9510: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
9520: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
9530: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
9540: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
9550: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
9560: 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e 74  ntly 2) */.  int
9570: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
9580: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
9590: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
95a0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
95b0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
95c0: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
95d0: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
95e0: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
95f0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
9600: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
9610: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
9620: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9630: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
9640: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
9650: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
9660: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
9670: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
9680: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
9690: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
96a0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
96b0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
96c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
96d0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
96e0: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
96f0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
9700: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
9710: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
9720: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9730: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9740: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
9750: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
9760: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9770: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9780: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
9790: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
97a0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
97b0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
97c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
97d0: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
97e0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
97f0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
9800: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9810: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
9820: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
9830: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
9840: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
9850: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
9860: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
9870: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
9880: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
9890: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
98a0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
98b0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
98c0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
98d0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
98e0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
98f0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
9900: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
9910: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
9920: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
9930: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
9940: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
9950: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
9960: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
9970: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
9980: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9990: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
99a0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
99b0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
99c0: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
99d0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
99e0: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
99f0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
9a00: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
9a10: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
9a20: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
9a30: 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
9a40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9a50: 68 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73 74  har *zOld, const
9a60: 20 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69 6e 74   char *zNew, int
9a70: 20 64 69 72 53 79 6e 63 29 3b 0a 20 20 69 6e 74   dirSync);.  int
9a80: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
9a90: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
9aa0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
9ab0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
9ac0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9ad0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
9ae0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
9af0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9b00: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
9b10: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9b20: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
9b30: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
9b40: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
9b50: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
9b60: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
9b70: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
9b80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9b90: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
9ba0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
9bb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
9bc0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
9bd0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
9be0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
9bf0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
9c00: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
9c10: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
9c20: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
9c30: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
9c40: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
9c50: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
9c60: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
9c70: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
9c80: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
9c90: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
9ca0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
9cb0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9cc0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
9cd0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9ce0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
9cf0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9d00: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
9d10: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
9d20: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
9d30: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a   and writable..*
9d40: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
9d50: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
9d60: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9d70: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9d80: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
9d90: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
9da0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
9db0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
9dc0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9dd0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
9de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9df0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
9e00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9e10: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
9e20: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
9e30: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
9e40: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
9e50: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
9e60: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
9e70: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
9e80: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
9e90: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
9ea0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
9eb0: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
9ec0: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
9ed0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
9ee0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
9ef0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
9f00: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
9f10: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
9f20: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
9f30: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
9f40: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
9f50: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
9f60: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
9f70: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
9f80: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
9f90: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
9fa0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
9fb0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
9fc0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
9fd0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
9fe0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
9ff0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
a000: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
a010: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
a020: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
a030: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
a040: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
a050: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
a060: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
a070: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
a080: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
a090: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
a0a0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
a0b0: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
a0c0: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
a0d0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
a0e0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
a0f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a100: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
a110: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
a120: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
a130: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
a140: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
a150: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
a160: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
a170: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
a180: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
a190: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
a1a0: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
a1b0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
a1c0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a1d0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
a1e0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
a1f0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
a200: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
a210: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
a220: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
a230: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
a240: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
a250: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
a260: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
a270: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
a280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a290: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
a2a0: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
a2b0: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
a2c0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
a2d0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
a2e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a2f0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
a300: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
a310: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
a320: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
a330: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
a340: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
a350: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
a360: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
a370: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
a380: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
a390: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
a3a0: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
a3b0: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
a3c0: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
a3d0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
a3e0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
a3f0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
a400: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
a410: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
a420: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
a430: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
a440: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
a450: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
a460: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a470: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
a480: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
a490: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
a4a0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
a4b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
a4c0: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
a4d0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
a4e0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
a4f0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
a500: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
a510: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
a520: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
a530: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
a540: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a550: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
a560: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
a570: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
a580: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
a590: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
a5a0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
a5b0: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
a5c0: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
a5d0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
a5e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a5f0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
a600: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
a610: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
a620: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
a630: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
a640: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
a650: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
a660: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
a670: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
a680: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a690: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
a6a0: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
a6b0: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
a6c0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
a6d0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
a6e0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
a6f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a700: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a710: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
a720: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
a730: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
a740: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
a750: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a760: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
a770: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
a780: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
a790: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
a7a0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
a7b0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
a7c0: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
a7d0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
a7e0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
a7f0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
a800: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
a810: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
a820: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
a830: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
a840: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
a850: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
a860: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
a870: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
a880: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
a890: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
a8a0: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
a8b0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
a8c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
a8d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
a8e0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
a8f0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
a900: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
a910: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
a920: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a930: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
a940: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
a950: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
a960: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
a970: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
a980: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
a990: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
a9a0: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
a9b0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
a9c0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
a9d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
a9e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a9f0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
aa00: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
aa10: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
aa20: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
aa30: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
aa40: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
aa50: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
aa60: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
aa70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aa80: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
aa90: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
aaa0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
aab0: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
aac0: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
aad0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
aae0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
aaf0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
ab00: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
ab10: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
ab20: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
ab30: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
ab40: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
ab50: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
ab60: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
ab70: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
ab80: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
ab90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
aba0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
abb0: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
abc0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
abd0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
abe0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
abf0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
ac00: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
ac10: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
ac20: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
ac30: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
ac40: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
ac50: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
ac60: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
ac70: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
ac80: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
ac90: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
aca0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
acb0: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
acc0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
acd0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
ace0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
acf0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
ad00: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
ad10: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
ad20: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
ad30: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
ad40: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
ad50: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
ad60: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
ad70: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
ad80: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
ad90: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
ada0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
adb0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
adc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
add0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
ade0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
adf0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
ae00: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
ae10: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
ae20: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
ae30: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
ae40: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
ae50: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
ae60: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
ae70: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
ae80: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
ae90: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
aea0: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
aeb0: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
aec0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
aed0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
aee0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
aef0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
af00: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
af10: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
af20: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
af30: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
af40: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
af50: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
af60: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
af70: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
af80: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
af90: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
afa0: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
afb0: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
afc0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
afd0: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
afe0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
aff0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
b000: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b010: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
b020: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
b030: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
b040: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
b050: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
b060: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
b070: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b080: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
b090: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
b0a0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
b0b0: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
b0c0: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
b0d0: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
b0e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
b0f0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
b100: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
b110: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
b120: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
b130: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
b140: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
b150: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
b160: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
b170: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
b180: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
b190: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
b1a0: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
b1b0: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
b1c0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
b1d0: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
b1e0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
b1f0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
b200: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
b210: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
b220: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
b230: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
b240: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
b250: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
b260: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
b270: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
b280: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
b290: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
b2a0: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
b2b0: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
b2c0: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
b2d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b2e0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
b2f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
b300: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
b310: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
b320: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
b330: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
b340: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
b350: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
b360: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
b370: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
b380: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
b390: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
b3a0: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
b3b0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
b3c0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
b3d0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
b3e0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
b3f0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
b400: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
b410: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
b420: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
b430: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
b440: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
b450: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
b460: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
b470: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
b480: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
b490: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
b4a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
b4b0: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
b4c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
b4d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
b4e0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
b4f0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
b500: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
b510: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
b520: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
b530: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
b540: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
b550: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
b560: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b570: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
b580: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
b590: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
b5a0: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
b5b0: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
b5c0: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
b5d0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
b5e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b5f0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
b600: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
b610: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
b620: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
b630: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
b640: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
b650: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
b660: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
b670: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b680: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
b690: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
b6a0: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
b6b0: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
b6c0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
b6d0: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
b6e0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
b6f0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
b700: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
b710: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
b720: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
b730: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
b740: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
b750: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
b760: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
b770: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
b780: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
b790: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
b7a0: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
b7b0: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
b7c0: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
b7d0: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
b7e0: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
b7f0: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
b800: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49  ing on the [SQLI
b810: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
b820: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
b830: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
b840: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
b850: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
b860: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
b870: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
b880: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
b890: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
b8a0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
b8b0: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
b8c0: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
b8d0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
b8e0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
b8f0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
b900: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
b910: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
b920: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
b930: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
b940: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
b950: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
b960: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b970: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
b980: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
b990: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
b9a0: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
b9b0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
b9c0: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
b9d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
b9e0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
b9f0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
ba00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ba10: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
ba20: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
ba30: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
ba40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ba50: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
ba60: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
ba70: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a  rgument).  The.*
ba80: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  * sqlite3_db_con
ba90: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
baa0: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75  should only be u
bab0: 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  sed immediately 
bac0: 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74  after.** the dat
bad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bae0: 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
baf0: 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
bb00: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
bb10: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
bb20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
bb30: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].  .**.** The s
bb40: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
bb50: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
bb60: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
bb70: 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72   the.** configur
bb80: 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20  ation verb - an 
bb90: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
bba0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
bbb0: 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68  .** aspect of th
bbc0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
bbd0: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
bbe0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
bbf0: 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20  The only choice 
bc00: 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69  for this value i
bc10: 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  s [SQLITE_DBCONF
bc20: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a  IG_LOOKASIDE]..*
bc30: 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20  * New verbs are 
bc40: 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64  likely to be add
bc50: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
bc60: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
bc70: 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61  .** Additional a
bc80: 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20  rguments depend 
bc90: 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a  on the verb..**.
bca0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
bcb0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
bcc0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
bcd0: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
bce0: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
bcf0: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
bd00: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
bd10: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
bd20: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
bd30: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
bd40: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
bd50: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
bd60: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
bd70: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
bd80: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
bd90: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
bda0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
bdb0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
bdc0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
bdd0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
bde0: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
bdf0: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
be00: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
be10: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
be20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
be30: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
be40: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
be50: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
be60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
be70: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
be80: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
be90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
bea0: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
beb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
bec0: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
bed0: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
bee0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
bef0: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
bf00: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
bf10: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
bf20: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
bf30: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
bf40: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
bf50: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
bf60: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
bf70: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
bf80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
bf90: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
bfa0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
bfb0: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
bfc0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
bfd0: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
bfe0: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
bff0: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
c000: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
c010: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
c020: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
c030: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
c040: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
c050: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
c060: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
c070: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
c080: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
c090: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
c0a0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
c0b0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
c0c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c0d0: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
c0e0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
c0f0: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
c100: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
c110: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
c120: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
c130: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
c140: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
c150: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
c160: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
c170: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
c180: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
c190: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
c1a0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
c1b0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
c1c0: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
c1d0: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e  * The xMalloc an
c1e0: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
c1f0: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
c200: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61  he.** malloc() a
c210: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
c220: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
c230: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
c240: 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63  .** The xRealloc
c250: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72   method must wor
c260: 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29  k like realloc()
c270: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
c280: 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20  rd C library.** 
c290: 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69  with the excepti
c2a0: 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73  on that if the s
c2b0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
c2c0: 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65  o xRealloc is ze
c2d0: 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  ro,.** xRealloc 
c2e0: 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20  must be a no-op 
c2f0: 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65  - it must not pe
c300: 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61  rform any alloca
c310: 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c  tion or.** deall
c320: 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74  ocation.  ^SQLit
c330: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c340: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
c350: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
c360: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
c370: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
c380: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
c390: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20  to xRoundup..** 
c3a0: 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20  And so in cases 
c3b0: 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61  where xRoundup a
c3c0: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
c3d0: 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c  positive number,
c3e0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e  .** xRealloc can
c3f0: 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79   perform exactly
c400: 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64   as the standard
c410: 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63   library realloc
c420: 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20  () and.** still 
c430: 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65  be in compliance
c440: 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69   with this speci
c450: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  fication..**.** 
c460: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
c470: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
c480: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
c490: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
c4a0: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
c4b0: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
c4c0: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
c4d0: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
c4e0: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
c4f0: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
c500: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
c510: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
c520: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
c530: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
c540: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
c550: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
c560: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
c570: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
c580: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
c590: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
c5a0: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
c5b0: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
c5c0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
c5d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
c5e0: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
c5f0: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
c600: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
c610: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
c620: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
c630: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
c640: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
c650: 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
c660: 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
c670: 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
c680: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
c690: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c6a0: 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
c6b0: 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
c6c0: 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
c6d0: 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
c6e0: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
c6f0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
c700: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
c710: 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
c720: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
c730: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
c740: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
c750: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
c760: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
c770: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
c780: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
c790: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
c7a0: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
c7b0: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
c7c0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
c7d0: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
c7e0: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
c7f0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
c800: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
c810: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
c820: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
c830: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
c840: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
c850: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
c860: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
c870: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
c880: 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
c890: 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
c8a0: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
c8b0: 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
c8c0: 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
c8d0: 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
c8e0: 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
c8f0: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
c900: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
c910: 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
c920: 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
c930: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
c940: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c950: 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
c960: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
c970: 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
c980: 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
c990: 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
c9a0: 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
c9b0: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
c9c0: 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
c9d0: 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
c9e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c9f0: 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
ca00: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
ca10: 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
ca20: 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
ca30: 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
ca40: 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
ca50: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
ca60: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
ca70: 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
ca80: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
ca90: 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
caa0: 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
cab0: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
cac0: 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
cad0: 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
cae0: 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
caf0: 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
cb00: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
cb10: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cb20: 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
cb30: 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
cb40: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
cb50: 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
cb60: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
cb70: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
cb80: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
cb90: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
cba0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
cbb0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
cbc0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
cbd0: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
cbe0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
cbf0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
cc00: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
cc10: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
cc20: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
cc30: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
cc40: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
cc50: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
cc60: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
cc70: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
cc80: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
cc90: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
cca0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
ccb0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
ccc0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
ccd0: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
cce0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
ccf0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
cd00: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
cd10: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
cd20: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
cd30: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
cd40: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
cd50: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
cd60: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
cd70: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
cd80: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
cd90: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cda0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
cdb0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
cdc0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
cdd0: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
cde0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
cdf0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
ce00: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
ce10: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
ce20: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
ce30: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
ce40: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
ce50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ce60: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
ce70: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
ce80: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
ce90: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
cea0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
ceb0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
cec0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
ced0: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
cee0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
cef0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
cf00: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
cf10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
cf20: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
cf30: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
cf40: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
cf50: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
cf60: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
cf70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
cf80: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
cf90: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
cfa0: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
cfb0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
cfc0: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
cfd0: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
cfe0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
cff0: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
d000: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
d010: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d020: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
d030: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
d040: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d050: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
d060: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
d070: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
d080: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
d090: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
d0a0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
d0b0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
d0c0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
d0d0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
d0e0: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
d0f0: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
d100: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
d110: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
d120: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
d130: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
d140: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
d150: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
d160: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
d170: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
d180: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
d190: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
d1a0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
d1b0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
d1c0: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
d1d0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
d1e0: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
d1f0: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
d200: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
d210: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
d220: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
d230: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
d240: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
d250: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
d260: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
d270: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
d280: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
d290: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d2a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d2b0: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
d2c0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
d2d0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
d2e0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
d2f0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
d300: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
d310: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
d320: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
d330: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
d340: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
d350: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
d360: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
d370: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
d380: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
d390: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
d3a0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
d3b0: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
d3c0: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
d3d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d3e0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
d3f0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
d400: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
d410: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
d420: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
d430: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
d440: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
d450: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
d460: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
d470: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
d480: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
d490: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
d4a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d4b0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
d4c0: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
d4d0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
d4e0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
d4f0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
d500: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
d510: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
d520: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
d530: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
d540: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
d550: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
d560: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
d570: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d580: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
d590: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
d5a0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
d5b0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
d5c0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
d5d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d5e0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
d5f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d600: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
d610: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
d620: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
d630: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
d640: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
d650: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
d660: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
d670: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
d680: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
d690: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d6a0: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d6b0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d6c0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d6d0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d6e0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d6f0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d700: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d710: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d720: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d730: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d740: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d750: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d760: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d770: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d780: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d790: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
d7a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d7b0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
d7c0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
d7d0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
d7e0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
d7f0: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
d800: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d810: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
d820: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
d830: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
d840: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
d850: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
d860: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
d870: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
d880: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
d890: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
d8a0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
d8b0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
d8c0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
d8d0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
d8e0: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
d8f0: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
d900: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
d910: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d920: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
d930: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
d940: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
d950: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
d960: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
d970: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d980: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
d990: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
d9a0: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
d9b0: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
d9c0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
d9d0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
d9e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d9f0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
da00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
da10: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
da20: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
da30: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
da40: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
da50: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
da60: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
da70: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
da80: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
da90: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
daa0: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
dab0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
dac0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
dad0: 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
dae0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
daf0: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
db00: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
db10: 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
db20: 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
db30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
db40: 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
db50: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
db60: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
db70: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
db80: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
db90: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
dba0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
dbb0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
dbc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
dbd0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
dbe0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
dbf0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
dc00: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
dc10: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
dc20: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
dc30: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
dc40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
dc50: 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
dc60: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
dc70: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
dc80: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
dc90: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
dca0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
dcb0: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
dcc0: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
dcd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
dce0: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
dcf0: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
dd00: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
dd10: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dd20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
dd30: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
dd40: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
dd50: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
dd60: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
dd70: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
dd80: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
dd90: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
dda0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
ddb0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
ddc0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ddd0: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
dde0: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
ddf0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
de00: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
de10: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
de20: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
de30: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
de40: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
de50: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
de60: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
de70: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
de80: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
de90: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
dea0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
deb0: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
dec0: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  imit()].**   <li
ded0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
dee0: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
def0: 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
df00: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
df10: 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
df20: 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
df30: 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
df40: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
df50: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
df60: 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
df70: 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
df80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
df90: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
dfa0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
dfb0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
dfc0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
dfd0: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
dfe0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
dff0: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
e000: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
e010: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
e020: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
e030: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
e040: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e050: 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
e060: 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
e070: 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
e080: 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
e090: 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61  ich the scrach a
e0a0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
e0b0: 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
e0c0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
e0d0: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
e0e0: 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
e0f0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
e100: 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
e110: 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
e120: 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
e130: 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
e140: 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73  ple of 16. The s
e150: 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  z parameter shou
e160: 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65  ld be a few byte
e170: 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e  s.** larger than
e180: 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61   the actual scra
e190: 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72  tch space requir
e1a0: 65 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e  ed due to intern
e1b0: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20  al overhead..** 
e1c0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
e1d0: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
e1e0: 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
e1f0: 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
e200: 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
e210: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
e220: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
e230: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
e240: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
e250: 63 68 20 62 75 66 66 65 72 20 70 65 72 20 74 68  ch buffer per th
e260: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
e270: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
e280: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
e290: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
e2a0: 68 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 65  hreads.  ^SQLite
e2b0: 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72   will.** never r
e2c0: 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68  equire a scratch
e2d0: 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
e2e0: 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d 65  more than 6 time
e2f0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
e300: 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66  * page size. ^If
e310: 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
e320: 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  eds additional s
e330: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
e340: 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 73  yond .** what is
e350: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
e360: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
e370: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
e380: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e390: 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
e3a0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e3b0: 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
e3c0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
e3d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
e3e0: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
e3f0: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
e400: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e410: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e420: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e430: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e440: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e450: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
e460: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
e470: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
e480: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
e490: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
e4a0: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
e4b0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
e4c0: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
e4d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e4e0: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
e4f0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e500: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
e510: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e520: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
e530: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
e540: 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
e550: 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
e560: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
e570: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
e580: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e590: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
e5a0: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
e5b0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
e5c0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
e5d0: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
e5e0: 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
e5f0: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
e600: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
e610: 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
e620: 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
e630: 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
e640: 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
e650: 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
e660: 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
e670: 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
e680: 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
e690: 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
e6a0: 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
e6b0: 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
e6c0: 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
e6d0: 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
e6e0: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
e6f0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
e700: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
e710: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
e720: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
e730: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
e740: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
e750: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
e760: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
e770: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
e780: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
e790: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
e7a0: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
e7b0: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
e7c0: 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
e7d0: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
e7e0: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
e7f0: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
e800: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
e810: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
e820: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
e830: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
e840: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
e850: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
e860: 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c  ce..** ^The impl
e870: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
e880: 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65   use one or more
e890: 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72   of the N buffer
e8a0: 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65  s to hold .** me
e8b0: 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
e8c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65  information. The
e8d0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
e8e0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
e8f0: 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
e900: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
e910: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
e920: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
e930: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
e940: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
e950: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
e960: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
e970: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
e980: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
e990: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
e9a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
e9b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
e9c0: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
e9d0: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
e9e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
e9f0: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
ea00: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
ea10: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
ea20: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
ea30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
ea40: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
ea50: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
ea60: 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
ea70: 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
ea80: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
ea90: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
eaa0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
eab0: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
eac0: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
ead0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
eae0: 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
eaf0: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
eb00: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
eb10: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
eb20: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
eb30: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
eb40: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
eb50: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
eb60: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
eb70: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
eb80: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
eb90: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
eba0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
ebb0: 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
ebc0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
ebd0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
ebe0: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
ebf0: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
ec00: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
ec10: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
ec20: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
ec30: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
ec40: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
ec50: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
ec60: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
ec70: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
ec80: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
ec90: 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
eca0: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
ecb0: 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
ecc0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
ecd0: 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
ece0: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
ecf0: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
ed00: 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
ed10: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
ed20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ed30: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
ed40: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
ed50: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
ed60: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
ed70: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
ed80: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
ed90: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
eda0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
edb0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
edc0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
edd0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
ede0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
edf0: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
ee00: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
ee10: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
ee20: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
ee30: 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
ee40: 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
ee50: 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
ee60: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
ee70: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
ee80: 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
ee90: 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
eea0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
eeb0: 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
eec0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
eed0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
eee0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
eef0: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
ef00: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
ef10: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
ef20: 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
ef30: 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
ef40: 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
ef50: 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
ef60: 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
ef70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
ef80: 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
ef90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
efa0: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
efb0: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
efc0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
efd0: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
efe0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
eff0: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
f000: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f010: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f020: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f030: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f040: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
f050: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
f060: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f070: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f080: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
f090: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
f0a0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
f0b0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
f0c0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
f0d0: 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
f0e0: 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
f0f0: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
f100: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
f110: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
f120: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
f130: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
f140: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
f150: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
f160: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
f170: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
f180: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
f190: 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
f1a0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f1b0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
f1c0: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
f1d0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
f1e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
f1f0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
f200: 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
f210: 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
f220: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
f230: 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
f240: 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
f250: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
f260: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
f270: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
f280: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f290: 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
f2a0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
f2b0: 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
f2c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f2d0: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
f2e0: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
f2f0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
f300: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
f310: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
f320: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
f330: 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
f340: 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
f350: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
f360: 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
f370: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
f380: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
f390: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
f3a0: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
f3b0: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
f3c0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
f3d0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
f3e0: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
f3f0: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
f400: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
f410: 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
f420: 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
f430: 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
f440: 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
f450: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
f460: 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
f470: 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
f480: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
f490: 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
f4a0: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
f4b0: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
f4c0: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
f4d0: 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
f4e0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f4f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
f500: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
f510: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f520: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f530: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f540: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
f550: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
f560: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
f570: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
f580: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
f590: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
f5a0: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
f5b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f5c0: 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
f5d0: 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
f5e0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
f5f0: 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
f600: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
f610: 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
f620: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f630: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
f640: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f650: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f660: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f670: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f680: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
f690: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
f6a0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
f6b0: 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
f6c0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
f6d0: 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
f6e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
f6f0: 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
f700: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f720: 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
f730: 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
f740: 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
f750: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
f760: 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
f770: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
f780: 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
f790: 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
f7a0: 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
f7b0: 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
f7c0: 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
f7d0: 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
f7e0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f7f0: 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
f800: 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
f810: 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
f820: 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
f830: 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
f840: 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
f850: 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
f860: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
f870: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
f880: 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
f890: 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
f8a0: 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
f8b0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
f8c0: 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
f8d0: 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
f8e0: 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
f8f0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f900: 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
f910: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
f920: 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
f930: 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
f940: 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
f950: 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
f960: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
f970: 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
f980: 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
f990: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
f9a0: 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
f9b0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
f9c0: 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
f9d0: 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
f9e0: 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
f9f0: 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
fa00: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
fa10: 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
fa20: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
fa30: 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
fa40: 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
fa50: 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
fa60: 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
fa70: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
fa80: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
fa90: 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
faa0: 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
fab0: 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
fac0: 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
fad0: 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
fae0: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
faf0: 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
fb00: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
fb10: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
fb20: 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
fb30: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
fb40: 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
fb50: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
fb60: 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
fb70: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
fb80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fb90: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fba0: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
fbb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fbc0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
fbd0: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
fbe0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
fbf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
fc00: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
fc10: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
fc20: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
fc30: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
fc40: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
fc50: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
fc60: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
fc70: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
fc80: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
fc90: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
fca0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fcb0: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
fcc0: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
fcd0: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
fce0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
fcf0: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
fd00: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
fd10: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
fd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
fd30: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
fd40: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
fd50: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
fd60: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
fd70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
fd80: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
fd90: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
fda0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fdb0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
fdc0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
fdd0: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
fde0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
fdf0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
fe00: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
fe10: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
fe20: 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
fe30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
fe40: 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
fe50: 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
fe60: 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
fe70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
fe80: 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
fe90: 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
fea0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
feb0: 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
fec0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
fed0: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
fee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
fef0: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
ff00: 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
ff10: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
ff20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ff30: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
ff40: 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
ff50: 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f  unc, void* */../
ff60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
ff70: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
ff80: 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
ff90: 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
ffa0: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
ffb0: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
ffc0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
ffd0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
ffe0: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
fff0: 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
10000 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
10010 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
10020 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
10030 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
10040 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10050 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
10060 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
10070 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
10080 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
10090 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
100a0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
100b0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
100c0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
100d0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
100e0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
100f0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10100 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
10110 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
10120 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
10130 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10140 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
10150 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
10160 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10170 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
10180 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
10190 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
101a0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
101b0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
101c0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
101d0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
101e0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
101f0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
10200 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
10210 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
10220 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
10230 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
10240 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10250 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
10260 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
10270 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10280 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
10290 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
102a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
102b0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
102c0 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
102d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f  inter to an memo
102e0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
102f0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
10300 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
10310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
10320 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
10330 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10340 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
10350 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
10360 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
10370 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
10380 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
10390 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
103a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
103b0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
103c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
103d0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
103e0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
103f0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
10400 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
10410 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
10420 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
10430 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
10440 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
10450 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
10460 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
10470 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
10480 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
10490 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
104a0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
104b0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
104c0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
104d0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
104e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
104f0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
10500 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10510 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
10520 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
10530 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
10540 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
10550 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
10560 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66  r.** multiple of
10570 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b   8.  See also: [
10580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10590 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a  OKASIDE]</dd>.**
105a0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
105b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
105c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
105d0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
105e0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a   int int */.../*
105f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
10600 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
10610 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
10620 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
10630 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
10640 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
10650 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
10660 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
10670 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
10680 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
10690 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
106a0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
106b0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
106c0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
106d0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
106e0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
106f0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
10700 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
10710 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
10720 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
10730 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
10740 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
10750 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
10760 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
10770 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
10780 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
10790 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
107a0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
107b0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
107c0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
107d0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
107e0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
107f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
10800 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
10810 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
10820 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
10830 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
10840 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
10850 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
10860 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
10870 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
10880 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
10890 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
108a0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
108b0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
108c0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
108d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
108e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
108f0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
10900 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
10910 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
10920 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
10930 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
10940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10950 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
10960 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
10970 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
10980 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
10990 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
109a0 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
109b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
109c0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
109d0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
109e0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
109f0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
10a00 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
10a10 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
10a20 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
10a30 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
10a40 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
10a50 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
10a60 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
10a70 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
10a80 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
10a90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10aa0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
10ab0 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
10ac0 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
10ad0 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
10ae0 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
10af0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
10b00 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
10b10 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
10b20 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
10b30 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
10b40 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
10b50 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
10b60 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
10b70 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
10b80 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
10b90 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
10ba0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
10bb0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
10bc0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
10bd0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
10be0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
10bf0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
10c00 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
10c10 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
10c20 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
10c30 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
10c40 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
10c50 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
10c60 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
10c70 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
10c80 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
10c90 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
10ca0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
10cb0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
10cc0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
10cd0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
10ce0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
10cf0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
10d00 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
10d10 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
10d20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
10d30 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
10d40 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
10d50 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
10d60 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
10d70 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
10d80 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
10d90 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
10da0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
10db0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
10dc0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
10dd0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
10de0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
10df0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
10e00 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
10e10 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
10e20 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
10e30 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
10e40 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
10e50 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
10e60 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
10e70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
10e80 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
10e90 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
10ea0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
10eb0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
10ec0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
10ed0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
10ee0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10ef0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10f00 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
10f10 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
10f20 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
10f30 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
10f40 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
10f50 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
10f60 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
10f70 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
10f80 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
10f90 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
10fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10fb0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
10fc0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
10fd0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
10fe0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10ff0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
11000 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
11010 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
11020 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
11030 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
11040 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
11050 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
11060 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
11070 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11080 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
11090 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
110a0 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
110b0 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
110c0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
110d0 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
110e0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
110f0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
11100 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
11110 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
11120 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
11130 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
11140 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
11150 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
11160 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
11170 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
11180 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
11190 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
111a0 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
111b0 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
111c0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
111d0 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
111e0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
111f0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
11200 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
11210 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
11220 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
11230 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
11240 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
11250 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
11260 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
11270 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
11280 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
11290 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
112a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
112b0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
112c0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
112d0 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
112e0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
112f0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
11300 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
11310 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
11320 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
11330 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
11340 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
11350 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
11360 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
11370 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
11380 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
11390 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
113a0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
113b0 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
113c0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
113d0 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
113e0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
113f0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
11400 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
11410 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
11420 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
11430 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
11440 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
11450 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
11460 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
11470 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
11480 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
11490 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
114a0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
114b0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
114c0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
114d0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
114e0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
114f0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
11500 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
11510 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
11520 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
11530 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
11540 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
11550 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
11560 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
11570 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
11580 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
11590 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
115a0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
115b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
115c0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
115d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
115e0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
115f0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
11600 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
11610 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
11620 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
11630 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
11640 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
11650 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
11660 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
11670 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
11680 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11690 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
116a0 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
116b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
116c0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
116d0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
116e0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
116f0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
11700 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
11710 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
11720 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
11730 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
11740 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
11750 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
11760 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
11770 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
11780 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11790 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
117a0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
117b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
117c0 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
117d0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
117e0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
117f0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
11800 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
11810 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
11820 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
11830 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
11840 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
11850 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
11860 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
11870 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11880 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
11890 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
118a0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
118b0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
118c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
118d0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
118e0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
118f0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
11900 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
11910 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
11920 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
11930 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
11940 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
11950 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
11960 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
11970 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
11980 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
11990 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
119a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
119b0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
119c0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
119d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
119e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
119f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
11a00 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
11a10 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
11a20 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
11a30 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
11a40 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
11a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
11a60 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
11a70 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
11a80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
11a90 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
11aa0 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
11ab0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
11ac0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
11ad0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
11ae0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
11af0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
11b00 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
11b10 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
11b20 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
11b30 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
11b40 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
11b50 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
11b60 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
11b70 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
11b80 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
11b90 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
11ba0 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
11bb0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
11bc0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
11bd0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
11be0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
11bf0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
11c00 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
11c10 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
11c20 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
11c30 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
11c40 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
11c50 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
11c60 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
11c70 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
11c80 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
11c90 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
11ca0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
11cb0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
11cc0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
11cd0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
11ce0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
11cf0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
11d00 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
11d10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
11d20 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
11d30 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
11d40 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
11d50 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
11d60 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
11d70 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
11d80 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
11d90 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
11da0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
11db0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11dc0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11dd0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11de0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
11df0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
11e00 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
11e10 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
11e20 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
11e30 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
11e40 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
11e50 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
11e60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11e70 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
11e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
11e90 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
11ea0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
11eb0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
11ec0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
11ed0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
11ee0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
11ef0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
11f00 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
11f10 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
11f20 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
11f30 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
11f40 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
11f50 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
11f60 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
11f70 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
11f80 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
11f90 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
11fa0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
11fb0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
11fc0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
11fd0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
11fe0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
11ff0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
12000 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
12010 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
12020 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
12030 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
12040 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
12050 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
12060 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
12070 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
12080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12090 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
120a0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
120b0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
120c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
120d0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
120e0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
120f0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
12100 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
12110 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
12120 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12130 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
12140 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
12150 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
12160 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
12170 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
12180 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
12190 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
121a0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
121b0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
121c0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
121d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
121e0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
121f0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
12200 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
12210 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
12220 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
12230 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
12240 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
12250 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
12260 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
12270 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
12280 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
12290 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
122a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
122b0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
122c0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
122d0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
122e0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
122f0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
12300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12310 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
12320 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
12330 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
12340 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
12350 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
12360 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
12370 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
12380 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
12390 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
123a0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
123b0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
123c0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
123d0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
123e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
123f0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
12400 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12410 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12420 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
12430 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
12440 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
12450 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
12460 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
12470 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
12480 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
12490 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
124a0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
124b0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
124c0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
124d0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
124e0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
124f0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
12500 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
12510 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
12520 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
12530 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
12540 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
12550 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
12560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
12570 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
12580 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
12590 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
125a0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
125b0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
125c0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
125d0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
125e0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
125f0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
12600 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
12610 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
12620 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12630 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
12640 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
12650 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
12660 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
12670 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
12680 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
12690 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
126a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
126b0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
126c0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
126d0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
126e0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
126f0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
12700 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
12710 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12720 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
12730 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
12740 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
12750 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
12760 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
12770 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
12780 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
12790 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
127a0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
127b0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
127c0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
127d0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
127e0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
127f0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
12800 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
12810 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
12820 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
12830 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
12840 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
12850 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
12860 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
12870 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
12880 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
12890 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
128a0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
128b0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
128c0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
128d0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
128e0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
128f0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
12900 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
12910 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
12920 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
12930 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12940 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
12950 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
12960 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
12970 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
12980 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
12990 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
129a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
129b0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
129c0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
129d0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
129e0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
129f0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
12a00 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
12a10 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
12a20 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
12a30 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
12a40 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
12a50 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
12a60 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
12a70 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12a80 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
12a90 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12aa0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
12ab0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12ac0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
12ad0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
12ae0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
12af0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
12b00 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
12b10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
12b20 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
12b30 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
12b40 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
12b50 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
12b60 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
12b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
12b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
12b90 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
12ba0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
12bb0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
12bc0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
12bd0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
12be0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
12bf0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
12c00 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
12c10 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
12c20 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
12c30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
12c40 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
12c50 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
12c60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12c70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
12c80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12c90 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
12ca0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
12cb0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
12cc0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
12cd0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
12ce0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
12cf0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
12d00 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
12d10 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
12d20 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
12d30 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
12d40 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
12d50 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
12d60 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
12d70 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
12d80 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
12d90 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
12da0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12db0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
12dc0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
12dd0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
12de0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
12df0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
12e00 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
12e10 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
12e20 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
12e30 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
12e40 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
12e50 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
12e60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12e70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12e80 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
12e90 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
12ea0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
12eb0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
12ec0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
12ed0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
12ee0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12ef0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
12f00 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
12f10 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
12f20 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
12f30 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
12f40 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
12f50 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
12f60 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
12f70 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
12f80 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
12f90 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
12fa0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
12fb0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
12fc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
12fd0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
12fe0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
12ff0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
13000 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
13010 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
13020 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
13030 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
13040 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
13050 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
13060 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
13070 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
13080 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
13090 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
130a0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
130b0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
130c0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
130d0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
130e0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
130f0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
13100 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
13110 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
13120 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
13130 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
13140 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
13150 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
13160 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
13170 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
13180 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13190 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
131a0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
131b0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
131c0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
131d0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
131e0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
131f0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
13200 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
13210 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
13220 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
13230 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
13240 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
13250 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
13260 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
13270 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
13280 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
13290 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
132a0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
132b0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
132c0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
132d0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
132e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
132f0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
13300 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
13310 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
13320 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
13330 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
13340 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
13350 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
13360 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
13370 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
13380 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
13390 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
133a0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
133b0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
133c0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
133d0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
133e0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
133f0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
13400 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
13410 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
13420 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
13430 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
13440 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
13450 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
13460 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
13470 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
13480 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
13490 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
134a0 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
134b0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
134c0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
134d0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
134e0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
134f0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
13500 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
13510 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
13520 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
13530 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
13540 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
13550 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
13560 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
13570 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
13580 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
13590 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
135a0 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
135b0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
135c0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
135d0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
135e0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
135f0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
13600 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
13610 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
13620 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
13630 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
13640 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
13650 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
13660 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
13670 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
13680 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
13690 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
136a0 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
136b0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
136c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
136d0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
136e0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
136f0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
13700 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
13710 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
13720 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
13730 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
13740 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
13750 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
13760 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
13770 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13780 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
13790 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
137a0 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
137b0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
137c0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
137d0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
137e0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
137f0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
13800 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
13810 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
13820 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
13830 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
13840 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
13850 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
13860 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
13870 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
13880 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
13890 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
138a0 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
138b0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
138c0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
138d0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
138e0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
138f0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
13900 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
13910 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
13920 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
13930 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
13940 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
13950 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
13960 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
13970 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
13980 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
13990 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
139a0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
139b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
139c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
139d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
139e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
139f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
13a00 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
13a10 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
13a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13a30 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
13a40 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
13a50 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
13a60 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
13a70 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
13a80 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
13a90 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
13aa0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
13ab0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
13ac0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
13ad0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
13ae0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
13af0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
13b00 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
13b10 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
13b20 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
13b30 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
13b40 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
13b50 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
13b60 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
13b70 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
13b80 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
13b90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
13ba0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
13bb0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
13bc0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13bd0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
13be0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
13bf0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
13c00 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
13c10 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
13c20 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
13c30 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
13c40 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
13c50 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
13c60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
13c70 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
13c80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13c90 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
13ca0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
13cb0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
13cc0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
13cd0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
13ce0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13cf0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
13d00 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
13d10 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
13d20 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
13d30 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
13d40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
13d50 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
13d60 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
13d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13d80 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
13d90 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
13da0 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44   Queries.**.** D
13db0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
13dc0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
13dd0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
13de0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
13df0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
13e00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13e10 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
13e20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
13e30 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
13e40 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
13e50 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
13e60 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
13e70 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
13e80 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
13e90 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
13ea0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
13eb0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
13ec0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
13ed0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
13ee0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
13ef0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
13f00 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
13f10 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
13f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
13f30 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
13f40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
13f50 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
13f60 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
13f70 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
13f80 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
13f90 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
13fa0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
13fb0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
13fc0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
13fd0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
13fe0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
13ff0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14000 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14010 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14020 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14030 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14040 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14050 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14060 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14070 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
14080 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
14090 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
140a0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
140b0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
140c0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
140d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
140e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
140f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
14100 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
14110 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
14120 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
14130 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
14140 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
14150 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
14160 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
14170 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
14180 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
14190 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
141a0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
141b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
141c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
141d0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
141e0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
141f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
14200 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
14210 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
14220 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
14230 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
14240 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
14250 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
14260 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
14270 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
14280 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
14290 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
142a0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
142b0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
142c0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
142d0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
142e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
142f0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
14300 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
14310 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
14320 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
14330 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
14340 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
14350 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
14360 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
14370 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
14380 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
14390 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
143a0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
143b0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
143c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
143d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
143e0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
143f0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
14400 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
14410 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
14420 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
14430 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
14440 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14450 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
14460 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14470 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
14480 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14490 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
144a0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
144b0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
144c0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
144d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
144e0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
144f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14500 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  >.**.** ^The sql
14510 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14520 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
14530 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
14540 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
14550 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
14560 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
14570 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14580 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
14590 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
145a0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
145b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
145c0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
145d0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
145e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
145f0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
14600 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
14610 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
14620 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
14630 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
14640 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20   it should pass 
14650 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
14660 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
14670 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14680 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
14690 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
146a0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
146b0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
146c0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
146d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
146e0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
146f0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
14700 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
14710 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
14720 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
14730 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
14740 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
14750 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
14760 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
14770 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
14780 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
14790 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
147a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
147b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
147c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
147d0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
147e0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
147f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14800 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14810 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14820 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14830 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
14840 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
14850 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
14860 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
14870 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
14880 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
14890 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
148a0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
148b0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
148c0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
148d0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
148e0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
148f0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14900 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14910 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
14920 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
14930 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
14940 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
14950 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
14960 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
14970 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
14980 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
14990 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
149a0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
149b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
149c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
149d0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
149e0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
149f0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
14a00 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
14a10 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
14a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
14a30 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
14a40 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
14a50 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
14a60 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
14a70 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
14a80 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
14a90 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
14aa0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
14ab0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
14ac0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
14ad0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
14ae0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
14af0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
14b00 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
14b10 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
14b20 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
14b30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
14b40 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
14b50 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
14b60 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
14b70 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
14b80 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
14b90 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
14ba0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
14bb0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
14bc0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
14bd0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
14be0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
14bf0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
14c00 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
14c10 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
14c20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
14c30 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
14c40 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
14c50 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
14c60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14c70 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
14c80 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
14c90 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
14ca0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14cb0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
14cc0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
14cd0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
14ce0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
14cf0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ring..**.** ^(In
14d00 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
14d10 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
14d20 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
14d30 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
14d40 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
14d50 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
14d60 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
14d70 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
14d80 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
14d90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14da0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
14db0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
14dc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
14dd0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
14de0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
14df0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
14e00 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
14e10 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
14e20 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
14e30 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
14e40 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
14e50 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
14e60 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
14e70 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
14e80 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
14e90 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
14ea0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
14eb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
14ec0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
14ed0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
14ee0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
14ef0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
14f00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
14f10 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
14f20 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
14f30 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
14f40 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
14f50 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
14f60 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
14f70 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
14f80 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
14f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
14fa0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14fb0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
14fc0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
14fd0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
14fe0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
14ff0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
15000 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
15010 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
15020 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
15030 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
15040 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
15050 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
15060 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
15070 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
15080 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
15090 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
150a0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
150b0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
150c0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
150d0 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
150e0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
150f0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
15100 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
15110 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
15120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
15130 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
15140 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
15150 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
15160 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
15170 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
15180 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
15190 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
151a0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
151b0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
151c0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
151d0 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
151e0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
151f0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
15200 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
15210 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
15220 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
15230 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
15240 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
15250 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
15260 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
15270 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
15280 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
15290 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
152a0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
152b0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
152c0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
152d0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
152e0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
152f0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
15300 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
15310 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
15320 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
15330 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
15340 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
15350 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
15360 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
15370 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
15380 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
15390 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
153a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
153b0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
153c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
153d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
153e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
153f0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
15400 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
15410 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
15420 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15430 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15440 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
15450 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
15460 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
15470 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
15480 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
15490 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
154a0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
154b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
154c0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
154d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
154e0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
154f0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
15500 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
15510 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
15520 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
15530 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
15540 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
15550 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15560 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15570 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
15580 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
15590 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
155a0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
155b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
155c0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
155d0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
155e0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
155f0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
15600 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
15610 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
15620 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15630 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
15640 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
15650 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
15660 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
15670 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
15680 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
15690 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
156a0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
156b0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
156c0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
156d0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
156e0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
156f0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
15700 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
15710 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
15720 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
15730 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
15740 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
15750 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
15760 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
15770 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
15780 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
15790 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
157a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
157b0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
157c0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
157d0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
157e0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
157f0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
15800 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
15810 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
15820 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
15830 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
15840 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15850 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
15860 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
15870 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
15880 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
15890 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
158a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
158b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
158c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
158d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
158e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
158f0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
15900 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
15910 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
15920 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
15930 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
15940 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
15950 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
15960 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
15970 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
15980 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
15990 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
159a0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
159b0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
159c0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
159d0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
159e0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
159f0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
15a00 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
15a10 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
15a20 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
15a30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
15a40 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
15a50 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
15a60 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
15a70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
15a80 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
15a90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
15aa0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
15ab0 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
15ac0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
15ad0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
15ae0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
15af0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
15b00 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
15b10 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
15b20 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
15b30 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
15b40 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
15b50 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
15b60 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
15b70 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
15b80 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
15b90 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
15ba0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
15bb0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
15bc0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
15bd0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15be0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
15bf0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
15c00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
15c10 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
15c20 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
15c30 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
15c40 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
15c50 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
15c60 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
15c70 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
15c80 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
15c90 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
15ca0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
15cb0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
15cc0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
15cd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
15ce0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
15cf0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
15d00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
15d10 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
15d20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
15d30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
15d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
15d50 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
15d60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
15d70 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
15d80 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
15d90 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
15da0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
15db0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
15dc0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
15dd0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
15de0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
15df0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
15e00 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
15e10 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
15e20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
15e30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
15e40 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
15e50 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
15e60 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
15e70 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
15e80 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
15e90 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
15ea0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
15eb0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
15ec0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
15ed0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
15ee0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
15ef0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
15f00 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
15f10 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
15f20 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
15f30 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
15f40 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
15f50 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
15f60 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
15f70 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
15f80 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
15f90 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
15fa0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
15fb0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
15fc0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
15fd0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
15fe0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
15ff0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
16000 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
16010 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
16020 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
16030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16040 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
16050 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
16060 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
16070 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
16080 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
16090 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
160a0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
160b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
160c0 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
160d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
160e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
160f0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
16100 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
16110 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
16120 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
16130 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
16140 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
16150 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16160 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
16170 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
16180 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16190 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
161a0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
161b0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
161c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
161d0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
161e0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
161f0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
16200 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
16210 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16220 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16230 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
16240 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16250 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16260 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
16270 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
16280 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
16290 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
162a0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
162b0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
162c0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
162d0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
162e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
162f0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
16300 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
16310 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16320 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
16330 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
16340 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
16350 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
16360 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
16370 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16380 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
16390 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
163a0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
163b0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
163c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
163d0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
163e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
163f0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
16400 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
16410 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
16420 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
16430 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
16440 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
16450 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  boundary..**.** 
16460 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
16470 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
16480 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
16490 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
164a0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
164b0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
164c0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
164d0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
164e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
164f0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
16500 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
16510 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
16520 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
16530 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
16540 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
16550 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
16560 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
16570 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
16580 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
16590 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
165a0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
165b0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
165c0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
165d0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
165e0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
165f0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
16600 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
16610 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
16620 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
16630 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
16640 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
16650 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
16660 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
16670 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
16680 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
16690 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
166a0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
166b0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
166c0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
166d0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
166e0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
166f0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
16700 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
16710 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
16720 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16730 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
16740 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
16750 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
16760 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
16770 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
16780 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
16790 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
167a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
167b0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
167c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
167d0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
167e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
167f0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
16800 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
16810 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
16820 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
16830 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
16840 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
16850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
16860 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
16870 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
16880 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
16890 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
168a0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
168b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
168c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
168d0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
168e0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
168f0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
16900 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
16910 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
16920 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
16930 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
16940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
16950 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
16960 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
16970 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16980 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
16990 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
169a0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
169b0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
169c0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
169d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
169e0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
169f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16a00 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
16a10 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
16a20 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
16a30 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
16a40 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
16a50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16a60 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
16a70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
16a80 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
16a90 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
16aa0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
16ab0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
16ac0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
16ad0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
16ae0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
16af0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
16b00 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
16b10 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
16b20 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
16b30 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
16b40 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
16b50 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
16b60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
16b70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16b80 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
16b90 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
16ba0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
16bb0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
16bc0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
16bd0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
16be0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
16bf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
16c00 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
16c10 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
16c20 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
16c30 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
16c40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
16c50 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
16c60 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
16c70 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
16c80 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
16c90 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
16ca0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
16cb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
16cc0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
16cd0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
16ce0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
16cf0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
16d00 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
16d10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16d20 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
16d30 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
16d40 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
16d50 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
16d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16d70 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
16d80 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
16d90 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
16da0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
16db0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
16dc0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
16dd0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
16de0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
16df0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
16e00 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
16e10 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
16e20 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
16e30 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
16e40 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
16e50 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
16e60 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
16e70 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
16e80 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
16e90 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
16ea0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
16eb0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
16ec0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
16ed0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
16ee0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
16ef0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
16f00 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
16f10 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
16f20 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
16f30 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
16f40 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
16f50 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
16f60 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
16f70 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
16f80 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
16f90 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
16fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
16fb0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
16fc0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
16fd0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
16fe0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
16ff0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
17000 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
17010 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
17020 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
17030 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
17040 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
17050 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
17060 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
17070 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
17080 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
17090 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
170a0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
170b0 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
170c0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
170d0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
170e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
170f0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
17100 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
17110 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
17120 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
17130 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
17140 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
17150 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
17160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17170 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
17180 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17190 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
171a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
171b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
171c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
171d0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
171e0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
171f0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
17200 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
17210 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17220 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
17230 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
17240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17250 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
17260 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
17270 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
17280 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
17290 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
172a0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
172b0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
172c0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
172d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
172e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
172f0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
17300 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
17310 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
17320 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17330 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
17340 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
17350 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
17360 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
17370 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
17380 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
17390 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
173a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
173b0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
173c0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
173d0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
173e0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
173f0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
17400 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
17410 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
17420 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
17430 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17440 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
17450 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
17460 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17470 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
17480 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
17490 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
174a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
174b0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
174c0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
174d0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
174e0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
174f0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
17500 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
17510 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17520 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17530 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
17540 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
17550 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
17560 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
17570 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
17580 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
17590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
175a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
175b0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
175c0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
175d0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
175e0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
175f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
17600 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
17610 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
17620 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
17630 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
17640 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
17650 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
17660 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
17670 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
17680 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
17690 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
176a0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
176b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
176c0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
176d0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
176e0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
176f0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
17700 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
17710 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
17720 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
17730 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
17740 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
17750 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
17760 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
17770 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
17780 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
17790 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
177a0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
177b0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
177c0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
177d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
177e0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
177f0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
17800 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
17810 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
17820 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
17830 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
17840 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
17850 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
17860 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
17870 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
17880 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
17890 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
178a0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
178b0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
178c0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
178d0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
178e0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
178f0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
17900 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
17910 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
17920 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
17930 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
17940 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
17950 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
17960 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
17970 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
17980 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
17990 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
179a0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
179b0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
179c0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
179d0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
179e0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
179f0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
17a00 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
17a10 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
17a20 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
17a30 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
17a40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
17a50 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
17a60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
17a70 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
17a80 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
17a90 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
17aa0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
17ab0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
17ac0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
17ad0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
17ae0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
17af0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
17b00 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
17b10 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
17b20 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
17b30 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
17b40 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
17b50 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
17b60 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
17b70 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
17b80 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
17b90 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
17ba0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
17bb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
17bc0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
17bd0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
17be0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
17bf0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
17c00 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17c10 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
17c20 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
17c30 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
17c40 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
17c50 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
17c60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
17c70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
17c80 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
17c90 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
17ca0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
17cb0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
17cc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
17cd0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
17ce0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
17cf0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
17d00 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
17d10 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
17d20 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
17d30 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
17d40 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
17d50 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
17d60 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
17d70 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
17d80 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
17d90 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
17da0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
17db0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
17dc0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
17dd0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
17de0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
17df0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
17e00 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
17e10 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
17e20 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
17e30 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
17e40 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
17e50 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
17e60 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
17e70 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
17e80 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
17e90 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
17ea0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
17eb0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
17ec0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
17ed0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
17ee0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
17ef0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
17f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
17f10 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
17f20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17f30 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
17f40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17f50 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
17f60 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
17f70 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
17f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17f90 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
17fa0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
17fb0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
17fc0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
17fd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17fe0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
17ff0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
18000 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
18010 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
18020 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
18030 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
18040 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
18050 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
18060 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
18070 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
18080 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
18090 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
180a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
180b0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
180c0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
180d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
180e0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
180f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18100 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18110 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
18120 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18130 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
18140 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
18150 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
18160 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
18170 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
18180 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
18190 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
181a0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
181b0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
181c0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
181d0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
181e0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
181f0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
18200 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
18210 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
18220 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
18230 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18240 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
18250 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
18260 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
18270 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
18280 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
18290 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
182a0 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
182b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
182c0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
182d0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
182e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
182f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
18300 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18310 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
18320 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
18330 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
18340 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
18350 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
18360 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
18370 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
18380 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
18390 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
183a0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
183b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
183c0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
183d0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
183e0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
183f0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
18400 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
18410 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
18420 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
18430 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
18440 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
18450 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
18460 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
18470 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
18480 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
18490 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
184a0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
184b0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
184c0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
184d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
184e0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
184f0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
18500 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18510 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
18520 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
18530 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
18540 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
18550 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
18560 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18570 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
18580 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
18590 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
185a0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
185b0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
185c0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
185d0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
185e0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
185f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18600 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
18610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
18620 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
18630 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
18640 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
18650 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
18660 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
18670 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
18680 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
18690 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
186a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
186b0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
186c0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
186d0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
186e0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
186f0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
18700 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
18710 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
18720 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
18730 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18740 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
18750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
18760 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
18770 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
18780 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
18790 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
187a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
187b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
187c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
187d0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
187e0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
187f0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
18800 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
18810 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
18820 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
18830 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
18840 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
18850 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
18860 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
18870 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18880 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
18890 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
188a0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
188b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
188c0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
188d0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
188e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
188f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18910 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
18920 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
18930 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18940 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18960 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
18970 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
18980 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
18990 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
189a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
189b0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
189c0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
189d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
189e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
189f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18a00 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
18a10 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
18a20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18a30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18a40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18a50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18a60 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
18a70 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18a80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18a90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18aa0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
18ab0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
18ac0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
18ad0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18ae0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
18af0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
18b00 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
18b10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18b20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18b30 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
18b40 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
18b50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18b60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18b70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18b80 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
18b90 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
18ba0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18bb0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18bc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18bd0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
18be0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
18bf0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18c00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18c10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18c20 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
18c30 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
18c40 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
18c50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c70 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
18c80 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
18c90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18ca0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18cc0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
18cd0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
18ce0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
18cf0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d10 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
18d20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
18d30 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
18d40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d60 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
18d70 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
18d80 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
18d90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18db0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
18dc0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
18dd0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
18de0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
18e00 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
18e10 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
18e20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18e30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
18e50 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
18e60 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
18e70 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
18e80 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
18e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
18ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18eb0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
18ec0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
18ed0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
18ee0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
18ef0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18f00 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
18f10 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18f20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18f30 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
18f40 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
18f50 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
18f60 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18f70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18f80 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
18f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
18fa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18fb0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
18fc0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18fd0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
18fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
18ff0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
19000 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19010 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19020 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
19030 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
19040 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
19050 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
19060 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19070 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
19080 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
19090 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
190a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
190b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
190c0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
190d0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
190e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
190f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19100 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19110 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
19120 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
19130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19140 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19160 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
19170 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
19180 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19190 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
191a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
191b0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
191c0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
191d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
191e0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
191f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19200 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
19210 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
19220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
19230 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
19240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19250 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
19260 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
19270 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
19280 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
19290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
192a0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
192b0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
192c0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
192d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
192e0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
192f0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
19300 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19310 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
19320 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
19330 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
19340 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
19350 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
19360 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
19370 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
19380 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
19390 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
193a0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
193b0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
193c0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
193d0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
193e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
193f0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
19400 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
19410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19420 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19430 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
19440 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
19450 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
19460 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
19470 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
19480 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
19490 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
194a0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
194b0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
194c0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
194d0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
194e0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
194f0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
19500 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
19510 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
19520 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
19530 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
19540 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
19550 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
19560 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19570 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
19580 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
19590 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
195a0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
195b0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
195c0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
195d0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
195e0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
195f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19600 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
19610 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
19620 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
19630 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
19640 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f   took to run..*/
19650 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
19660 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
19670 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
19680 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
19690 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
196a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
196b0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
196c0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
196d0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
196e0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
196f0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
19700 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19710 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
19720 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
19730 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
19740 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
19750 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
19760 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
19770 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19780 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
19790 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
197a0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
197b0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
197c0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
197d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
197e0 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
197f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19800 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
19810 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
19820 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
19830 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
19840 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
19850 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49   query..**.** ^I
19860 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
19870 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19880 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
19890 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
198a0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
198b0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
198c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
198d0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
198e0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
198f0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
19900 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
19910 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
19920 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
19930 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
19940 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
19950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19960 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19970 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
19980 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
19990 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
199a0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
199b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
199c0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
199d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
199e0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
199f0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
19a00 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
19a10 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
19a20 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
19a30 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
19a40 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
19a50 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
19a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19a70 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
19a80 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
19a90 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
19aa0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
19ab0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
19ac0 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
19ad0 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
19ae0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
19af0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
19b00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
19b10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
19b20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
19b30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
19b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19b50 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
19b60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
19b70 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
19b80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19b90 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
19ba0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
19bb0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
19bc0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
19bd0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
19be0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
19bf0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
19c00 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
19c10 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
19c20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
19c30 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
19c40 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
19c50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
19c60 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
19c70 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
19c80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
19c90 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
19ca0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
19cb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
19cc0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
19cd0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
19ce0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
19cf0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
19d00 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
19d10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
19d20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
19d30 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
19d40 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
19d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
19d60 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
19d70 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
19d80 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
19d90 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
19da0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
19db0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
19dc0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
19dd0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
19de0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
19df0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
19e00 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
19e10 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
19e20 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
19e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
19e40 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
19e50 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
19e60 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
19e70 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
19e80 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
19e90 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
19ea0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
19eb0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
19ec0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
19ed0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
19ee0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
19ef0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
19f00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19f10 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
19f20 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
19f30 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
19f40 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
19f50 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
19f60 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
19f70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19f80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
19f90 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
19fa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
19fb0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
19fc0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
19fd0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
19fe0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
19ff0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1a000 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1a010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1a020 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1a030 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1a040 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1a050 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1a060 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1a070 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1a080 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1a090 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1a0a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1a0b0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1a0c0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1a0d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1a0e0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64  EDCACHE],.** and
1a0f0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1a100 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1a110 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1a120 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1a130 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1a140 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1a150 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a160 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1a170 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1a180 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1a190 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1a1a0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1a1b0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1a1c0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1a1d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a1e0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1a1f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1a200 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1a210 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1a220 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1a230 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1a240 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1a250 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1a260 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1a270 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1a280 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1a290 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1a2a0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1a2b0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1a2c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a2d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1a2e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a2f0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1a300 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1a310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a320 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a330 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1a340 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1a350 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a  s creates it if.
1a360 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1a370 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1a380 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1a390 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1a3a0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1a3b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a3c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a3d0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1a3e0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1a3f0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1a400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a410 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1a420 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1a430 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1a440 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1a450 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1a460 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1a470 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1a480 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1a490 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1a4a0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20  _FULLMUTEX],.** 
1a4b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1a4c0 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72  REDCACHE] and/or
1a4d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a4e0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73  AREDCACHE] flags
1a4f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
1a500 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
1a510 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
1a520 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1a530 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
1a540 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
1a550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a560 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
1a570 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
1a580 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1a590 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
1a5a0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
1a5b0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
1a5c0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
1a5d0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1a5e0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
1a5f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
1a600 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
1a610 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
1a620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a630 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
1a640 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1a650 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
1a660 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
1a670 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
1a680 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
1a690 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1a6a0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
1a6b0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
1a6c0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
1a6d0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1a6e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a6f0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
1a700 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
1a710 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1a720 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
1a730 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
1a740 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1a750 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
1a760 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1a770 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
1a780 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
1a790 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1a7a0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1a7b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a7c0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
1a7d0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
1a7e0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
1a7f0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
1a800 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
1a810 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1a820 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1a830 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1a840 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1a850 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1a860 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1a870 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1a880 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
1a890 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1a8a0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1a8b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a8c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1a8d0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1a8e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1a8f0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1a900 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1a910 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1a920 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1a930 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1a940 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1a950 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1a960 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1a970 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1a980 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1a990 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1a9a0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1a9b0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1a9c0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1a9d0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1a9e0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1a9f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
1aa00 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1aa10 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1aa20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1aa30 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1aa40 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1aa50 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1aa60 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
1aa70 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1aa80 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1aa90 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1aaa0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1aab0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1aac0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  osed..**.** ^The
1aad0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1aae0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1aaf0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1ab00 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1ab10 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1ab20 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1ab30 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1ab40 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1ab50 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1ab60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ab70 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
1ab80 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1ab90 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1aba0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1abb0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1abc0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1abd0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1abe0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
1abf0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
1ac00 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
1ac10 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
1ac20 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1ac30 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
1ac40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1ac50 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
1ac60 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
1ac70 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
1ac80 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
1ac90 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
1aca0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
1acb0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
1acc0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
1acd0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
1ace0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
1acf0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
1ad00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ad10 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1ad20 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  v2()..*/.int sql
1ad30 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
1ad40 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1ad50 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1ad60 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1ad70 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1ad80 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1ad90 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1ada0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1adb0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
1adc0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
1add0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1ade0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1adf0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
1ae00 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1ae10 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1ae20 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1ae30 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1ae40 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
1ae50 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1ae60 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1ae70 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1ae80 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1ae90 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
1aea0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1aeb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
1aec0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
1aed0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
1aee0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1aef0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
1af00 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
1af10 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
1af20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
1af30 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
1af40 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
1af50 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
1af60 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
1af70 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1af80 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
1af90 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1afa0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1afb0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1afc0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
1afd0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
1afe0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1aff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b000 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
1b010 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
1b020 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
1b030 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
1b040 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
1b050 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1b060 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
1b070 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
1b080 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
1b090 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1b0a0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
1b0b0 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
1b0c0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1b0d0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
1b0e0 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
1b0f0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
1b100 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
1b110 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
1b120 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
1b130 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b140 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
1b150 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b160 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
1b170 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
1b180 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1b190 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
1b1a0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1b1b0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
1b1c0 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
1b1d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1b1e0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1b1f0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1b200 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1b210 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1b220 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1b230 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1b240 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1b250 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1b260 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1b270 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1b280 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1b290 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1b2a0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1b2b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1b2c0 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
1b2d0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
1b2e0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1b2f0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
1b300 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
1b310 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
1b320 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
1b330 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
1b340 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
1b350 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
1b360 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
1b370 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
1b380 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
1b390 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
1b3a0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
1b3b0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
1b3c0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
1b3d0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
1b3e0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
1b3f0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
1b400 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
1b410 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
1b420 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
1b430 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
1b440 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
1b450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b460 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
1b470 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1b480 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
1b490 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1b4a0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
1b4b0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
1b4c0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1b4d0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
1b4e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1b4f0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
1b500 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
1b510 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
1b520 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
1b530 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
1b540 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
1b550 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
1b560 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
1b570 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
1b580 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
1b590 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
1b5a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
1b5b0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
1b5c0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
1b5d0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
1b5e0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
1b5f0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
1b600 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
1b610 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
1b620 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1b630 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1b640 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1b650 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
1b660 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
1b670 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
1b680 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
1b690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b6a0 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
1b6b0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1b6c0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
1b6d0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
1b6e0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
1b6f0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
1b700 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
1b710 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
1b720 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
1b730 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
1b740 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
1b750 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
1b760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
1b770 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
1b780 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
1b790 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
1b7a0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
1b7b0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
1b7c0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
1b7d0 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
1b7e0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1b7f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
1b800 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
1b810 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1b820 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b830 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
1b840 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
1b850 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
1b860 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
1b870 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
1b880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
1b890 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
1b8a0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
1b8b0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
1b8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1b8d0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
1b8e0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
1b8f0 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
1b900 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1b910 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
1b920 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
1b930 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
1b940 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
1b950 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1b960 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
1b970 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1b980 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1b990 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1b9a0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
1b9b0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
1b9c0 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
1b9d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1b9e0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1b9f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1ba00 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
1ba10 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
1ba20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1ba30 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
1ba40 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
1ba50 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1ba60 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1ba70 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1ba80 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1ba90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1baa0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1bab0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1bac0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1bad0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bae0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1baf0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1bb00 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1bb10 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1bb20 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1bb30 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1bb40 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1bb50 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1bb60 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1bb70 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1bb80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1bb90 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1bba0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1bbb0 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1bbc0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1bbd0 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29   the old limit.)
1bbe0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
1bbf0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1bc00 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1bc10 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1bc20 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
1bc30 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1bc40 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1bc50 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1bc60 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
1bc70 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1bc80 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63  d].** set by a c
1bc90 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72  ompile-time C pr
1bca0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1bcb0 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69   named .** [limi
1bcc0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1bcd0 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  XYZ]..** (The "_
1bce0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1bcf0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1bd00 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
1bd10 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
1bd20 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
1bd30 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
1bd40 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
1bd50 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
1bd60 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
1bd70 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
1bd80 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
1bd90 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1bda0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1bdb0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1bdc0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1bdd0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1bde0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
1bdf0 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
1be00 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
1be10 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
1be20 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
1be30 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
1be40 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
1be50 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
1be60 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
1be70 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
1be80 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
1be90 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
1bea0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
1beb0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
1bec0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
1bed0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
1bee0 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
1bef0 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
1bf00 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
1bf10 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
1bf20 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
1bf30 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
1bf40 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
1bf50 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
1bf60 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
1bf70 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
1bf80 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
1bf90 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
1bfa0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
1bfb0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
1bfc0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
1bfd0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
1bfe0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1bff0 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
1c000 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
1c010 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
1c020 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
1c030 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1c040 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
1c050 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
1c060 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
1c070 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
1c080 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1c090 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
1c0a0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
1c0b0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
1c0c0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
1c0d0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
1c0e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
1c0f0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
1c100 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
1c110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c120 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
1c130 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
1c140 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1c150 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
1c160 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
1c170 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
1c180 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
1c190 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
1c1a0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
1c1b0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
1c1c0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
1c1d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1c1e0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
1c1f0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
1c200 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
1c210 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
1c220 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
1c230 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1c240 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
1c250 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
1c260 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
1c270 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1c280 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c290 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1c2a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c2b0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1c2c0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1c2d0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a  ble row.<dd>)^.*
1c2e0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c2f0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1c300 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1c310 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1c320 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1c330 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
1c340 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c350 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c360 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1c370 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c380 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1c390 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1c3a0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1c3b0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1c3c0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
1c3d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1c3e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1c3f0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1c400 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1c410 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1c420 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
1c430 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c440 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1c450 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c460 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1c470 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1c480 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1c490 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c4a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c4b0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1c4c0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1c4d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c4e0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1c4f0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1c500 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1c510 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c520 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1c530 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1c540 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c550 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1c560 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1c570 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1c580 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1c590 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1c5a0 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
1c5b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c5c0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1c5d0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1c5e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c5f0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1c600 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1c610 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c620 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1c630 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1c640 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c650 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
1c660 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
1c670 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
1c680 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c690 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1c6a0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1c6b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c6c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1c6d0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1c6e0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1c6f0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1c700 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
1c710 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c720 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1c730 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
1c740 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c750 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62  number of variab
1c760 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  les in an SQL st
1c770 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e  atement that can
1c780 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64  .** be bound.</d
1c790 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1c7a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
1c7b0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
1c7c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c7d0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
1c7e0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
1c7f0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
1c800 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1c810 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c820 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1c830 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
1c840 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
1c850 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
1c860 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
1c870 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1c880 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
1c890 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
1c8a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c8b0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
1c8c0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
1c8d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c8e0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1c8f0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
1c900 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c910 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
1c920 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
1c930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c940 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
1c950 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
1c960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c970 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
1c980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
1c990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c9a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1c9b0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
1c9c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c9d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1c9e0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
1c9f0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
1ca00 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
1ca10 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1ca20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
1ca30 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
1ca40 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
1ca50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
1ca60 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
1ca70 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
1ca80 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
1ca90 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
1caa0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
1cab0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
1cac0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
1cad0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
1cae0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
1caf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
1cb00 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
1cb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cb20 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
1cb30 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
1cb40 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1cb50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1cb60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1cb70 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1cb80 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
1cb90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1cba0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
1cbb0 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
1cbc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1cbd0 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
1cbe0 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
1cbf0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
1cc00 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
1cc10 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1cc20 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
1cc30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cc40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1cc50 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
1cc60 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
1cc70 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
1cc80 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
1cc90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cca0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
1ccb0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
1ccc0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1ccd0 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
1cce0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
1ccf0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
1cd00 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
1cd10 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
1cd20 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
1cd30 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
1cd40 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
1cd50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
1cd60 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
1cd70 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
1cd80 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1cd90 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1cda0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1cdb0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1cdc0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1cdd0 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1cde0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1cdf0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1ce00 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1ce10 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1ce20 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1ce30 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1ce40 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1ce50 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1ce60 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1ce70 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1ce80 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1ce90 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1cea0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1ceb0 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1cec0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1ced0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1cee0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1cef0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1cf00 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1cf10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
1cf20 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
1cf30 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1cf40 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1cf50 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
1cf60 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1cf70 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1cf80 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1cf90 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1cfa0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
1cfb0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
1cfc0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
1cfd0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
1cfe0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
1cff0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
1d000 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
1d010 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
1d020 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
1d030 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
1d040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1d050 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
1d060 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
1d070 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
1d080 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
1d090 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
1d0a0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
1d0b0 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
1d0c0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
1d0d0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
1d0e0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
1d0f0 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
1d100 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
1d110 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
1d120 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
1d130 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1d140 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1d150 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1d160 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1d170 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1d180 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1d190 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1d1a0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1d1b0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
1d1c0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
1d1d0 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
1d1e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1d1f0 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
1d200 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
1d210 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
1d220 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1d230 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1d240 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1d250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d260 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
1d270 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
1d280 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
1d290 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
1d2a0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
1d2b0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
1d2c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1d2d0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
1d2e0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d2f0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
1d300 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
1d310 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
1d320 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1d330 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
1d340 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
1d350 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
1d360 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1d370 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
1d380 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
1d390 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
1d3a0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
1d3b0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
1d3c0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
1d3d0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
1d3e0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
1d3f0 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
1d400 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
1d410 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
1d420 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
1d430 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
1d440 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
1d450 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
1d460 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
1d470 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1d480 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
1d490 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
1d4a0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
1d4b0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
1d4c0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e  run it again.  ^
1d4d0 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
1d4e0 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
1d4f0 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
1d500 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
1d510 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
1d520 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d530 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
1d540 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
1d550 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69  HEMA].  But unli
1d560 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ke the legacy be
1d570 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f  havior, [SQLITE_
1d580 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f  SCHEMA] is.** no
1d590 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e  w a fatal error.
1d5a0 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74    Calling [sqlit
1d5b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d5c0 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
1d5d0 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
1d5e0 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
1d5f0 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
1d600 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
1d610 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
1d620 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
1d630 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
1d640 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
1d650 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20  EMA] return..** 
1d660 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1d670 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
1d680 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
1d690 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d6a0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
1d6b0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
1d6c0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
1d6d0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
1d6e0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
1d6f0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
1d700 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
1d710 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
1d720 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
1d730 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
1d740 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
1d750 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
1d760 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
1d770 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
1d780 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
1d790 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
1d7a0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
1d7b0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
1d7c0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
1d7d0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
1d7e0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
1d7f0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1d800 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
1d810 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
1d820 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1d830 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
1d840 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1d850 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f   ^If the value o
1d860 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c  f a [parameter |
1d870 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
1d880 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c   in the WHERE cl
1d890 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68  ause might.** ch
1d8a0 61 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70  ange the query p
1d8b0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
1d8c0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74  ent, then the st
1d8d0 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a  atement may be.*
1d8e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1d8f0 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69  recompiled (as i
1d900 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
1d910 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1d920 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a  ) on the first .
1d930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1d940 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
1d950 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f  ng any change to
1d960 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
1d970 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
1d980 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b  ndings] of the [
1d990 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
1d9a0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
1d9b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
1d9c0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
1d9d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1d9e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1d9f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1da00 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1da10 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1da20 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1da30 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1da40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1da50 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1da60 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1da70 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1da80 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1da90 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1daa0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1dab0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1dac0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1dad0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1dae0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1daf0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1db00 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
1db10 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1db20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1db30 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1db40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1db50 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1db60 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1db70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1db80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1db90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1dba0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1dbb0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1dbc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1dbd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1dbe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1dbf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1dc00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1dc10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1dc20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1dc30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1dc40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1dc50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1dc60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1dc70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1dc80 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1dc90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1dca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1dcb0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1dcc0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1dcd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1dce0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1dcf0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1dd00 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1dd10 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1dd20 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1dd30 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1dd40 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1dd50 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1dd60 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1dd70 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1dd80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1dd90 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
1dda0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ddb0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1ddc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1ddd0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1dde0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1ddf0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1de00 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1de10 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1de20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1de30 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1de40 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1de50 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1de60 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1de70 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1de80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1de90 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1dea0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1deb0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1dec0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
1ded0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
1dee0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1def0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
1df00 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1df10 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1df20 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1df30 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1df40 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1df50 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1df60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1df70 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
1df80 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
1df90 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1dfa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1dfb0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1dfc0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1dfd0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1dfe0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1dff0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1e000 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1e010 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
1e020 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
1e030 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
1e040 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1e050 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1e060 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e070 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1e080 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1e090 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e0a0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1e0b0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1e0c0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1e0d0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1e0e0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1e0f0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1e100 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1e110 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
1e120 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
1e130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e140 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
1e150 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
1e160 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
1e170 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
1e180 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
1e190 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
1e1a0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
1e1b0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
1e1c0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
1e1d0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
1e1e0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1e1f0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1e200 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
1e210 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1e220 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
1e230 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
1e240 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1e250 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1e260 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
1e270 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
1e280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
1e290 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
1e2a0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
1e2b0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
1e2c0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1e2d0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
1e2e0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
1e2f0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
1e300 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
1e310 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
1e320 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
1e330 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
1e340 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1e350 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
1e360 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1e370 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
1e380 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1e390 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
1e3a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1e3b0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
1e3c0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
1e3d0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
1e3e0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
1e3f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1e400 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
1e410 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1e420 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1e430 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
1e440 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
1e450 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
1e460 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
1e470 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1e480 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
1e490 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1e4a0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
1e4b0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1e4c0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1e4d0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1e4e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1e4f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e500 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1e510 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
1e520 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
1e530 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
1e540 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
1e550 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
1e560 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1e570 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
1e580 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1e590 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65  on between betwe
1e5a0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1e5b0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1e5c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e5d0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
1e5e0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
1e5f0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
1e600 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1e610 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
1e620 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
1e630 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
1e640 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1e650 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
1e660 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1e670 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
1e680 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
1e690 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e6a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1e6b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1e6c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1e6d0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1e6e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1e6f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e700 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1e710 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
1e720 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1e730 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e740 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
1e750 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
1e760 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
1e770 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
1e780 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
1e790 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1e7a0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
1e7b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e7c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
1e7d0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
1e7e0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
1e7f0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
1e800 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
1e810 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
1e820 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
1e830 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
1e840 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
1e850 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
1e860 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
1e870 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
1e880 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
1e890 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
1e8a0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
1e8b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
1e8c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1e8d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1e8e0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1e8f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1e900 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
1e910 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
1e920 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
1e930 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
1e940 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1e950 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
1e960 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
1e970 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
1e980 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
1e990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
1e9a0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
1e9b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
1e9c0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
1e9d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
1e9e0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
1e9f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
1ea00 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
1ea10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1ea20 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
1ea30 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
1ea40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
1ea50 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
1ea60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1ea70 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
1ea80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
1ea90 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1eaa0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
1eab0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
1eac0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
1ead0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
1eae0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
1eaf0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
1eb00 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
1eb10 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
1eb20 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
1eb30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1eb40 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
1eb50 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
1eb60 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
1eb70 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
1eb80 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
1eb90 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
1eba0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
1ebb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1ebc0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1ebd0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1ebe0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1ebf0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1ec00 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
1ec10 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
1ec20 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
1ec30 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
1ec40 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
1ec50 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
1ec60 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e  meric identifer.
1ec70 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
1ec80 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
1ec90 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
1eca0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
1ecb0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
1ecc0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
1ecd0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
1ece0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1ecf0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1ed00 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
1ed10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ed20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1ed30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1ed40 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
1ed50 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
1ed60 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1ed70 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
1ed80 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
1ed90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eda0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
1edb0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
1edc0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1edd0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1ede0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
1edf0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
1ee00 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
1ee10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
1ee20 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1ee30 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
1ee40 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1ee50 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1ee60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1ee70 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1ee80 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1ee90 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1eea0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1eeb0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1eec0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
1eed0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
1eee0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
1eef0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
1ef00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ef10 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1ef20 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
1ef30 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
1ef40 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
1ef50 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
1ef60 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
1ef70 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
1ef80 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1ef90 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
1efa0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1efb0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
1efc0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1efd0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
1efe0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
1eff0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
1f000 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1f010 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
1f020 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1f030 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
1f040 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
1f050 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
1f060 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
1f070 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f080 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1f090 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
1f0a0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
1f0b0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1f0c0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1f0d0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
1f0e0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
1f0f0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1f100 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
1f110 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1f120 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1f130 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1f140 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1f150 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1f160 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1f170 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1f180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
1f190 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1f1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1f1b0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
1f1c0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
1f1d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f1e0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
1f1f0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
1f200 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
1f210 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
1f220 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
1f230 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1f240 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
1f250 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
1f260 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1f270 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1f280 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
1f290 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
1f2a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1f2b0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
1f2c0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
1f2d0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1f2e0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
1f2f0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1f300 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
1f310 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
1f320 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
1f330 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
1f340 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
1f350 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
1f360 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
1f370 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
1f380 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
1f390 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1f3a0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1f3b0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1f3c0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1f3d0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1f3e0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1f3f0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
1f400 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
1f410 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
1f420 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
1f430 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
1f440 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
1f450 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
1f460 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
1f470 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
1f480 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
1f490 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1f4a0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
1f4b0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
1f4c0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
1f4d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
1f4e0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
1f4f0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
1f500 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
1f510 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
1f520 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
1f530 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
1f540 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
1f550 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
1f560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f570 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
1f580 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1f590 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
1f5a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f5b0 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
1f5c0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
1f5d0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
1f5e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1f5f0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
1f600 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
1f610 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
1f620 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
1f630 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
1f640 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1f650 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
1f660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
1f670 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
1f680 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
1f690 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1f6a0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
1f6b0 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
1f6c0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
1f6d0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
1f6e0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
1f6f0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
1f700 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
1f710 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f720 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
1f730 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
1f740 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
1f750 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
1f760 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1f770 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
1f780 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
1f790 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
1f7a0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
1f7b0 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
1f7c0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
1f7d0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1f7e0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1f7f0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1f800 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1f810 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
1f820 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
1f830 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
1f840 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1f850 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1f860 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1f870 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f880 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1f890 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
1f8a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f8b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1f8c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f8d0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1f8e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1f8f0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1f900 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1f910 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f920 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1f930 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1f940 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1f950 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1f960 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1f970 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1f980 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1f990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1f9a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1f9b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f9c0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1f9d0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1f9e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1f9f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1fa00 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1fa10 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1fa20 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1fa30 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1fa40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fa50 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1fa60 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1fa70 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1fa80 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1fa90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1faa0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1fab0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1fac0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1fad0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1fae0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1faf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fb00 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1fb10 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
1fb20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
1fb30 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
1fb40 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
1fb50 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
1fb60 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
1fb70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
1fb80 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
1fb90 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
1fba0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
1fbb0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
1fbc0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
1fbd0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
1fbe0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
1fbf0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1fc00 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1fc10 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1fc20 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1fc30 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1fc40 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
1fc50 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
1fc60 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
1fc70 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
1fc80 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
1fc90 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
1fca0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
1fcb0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
1fcc0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
1fcd0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1fce0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
1fcf0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
1fd00 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
1fd10 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
1fd20 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
1fd30 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
1fd40 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1fd50 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1fd60 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1fd70 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1fd80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fd90 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1fda0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1fdb0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1fdc0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1fdd0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fde0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1fdf0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1fe00 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
1fe10 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
1fe20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fe30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1fe40 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
1fe50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
1fe60 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
1fe70 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
1fe80 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
1fe90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fea0 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
1feb0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1fec0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1fed0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1fee0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1fef0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1ff00 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1ff10 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1ff20 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1ff30 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1ff40 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1ff50 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1ff60 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1ff70 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1ff80 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1ff90 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
1ffa0 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
1ffb0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
1ffc0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
1ffd0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
1ffe0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
1fff0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
20000 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
20010 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
20020 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
20030 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
20040 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
20050 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
20060 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
20070 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
20080 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
20090 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
200a0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
200b0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
200c0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
200d0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
200e0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
200f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
20100 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
20110 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
20120 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
20130 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
20140 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
20150 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
20160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20170 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
20180 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
20190 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
201a0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
201b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
201c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
201d0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
201e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
201f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
20200 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20210 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20220 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
20230 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
20240 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
20250 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
20260 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
20270 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
20280 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
20290 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
202a0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
202b0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
202c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
202d0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
202e0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
202f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
20300 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20310 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
20320 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
20330 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
20340 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
20350 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
20360 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
20370 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
20380 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
20390 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
203a0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
203b0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
203c0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
203d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
203e0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
203f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
20400 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20410 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
20420 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
20430 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
20440 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
20450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
20460 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
20470 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
20480 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
20490 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
204a0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
204b0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
204c0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
204d0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
204e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
204f0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
20500 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
20510 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
20520 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
20530 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
20540 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
20550 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
20560 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
20570 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
20580 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
20590 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
205a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
205b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
205c0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
205d0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
205e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
205f0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
20600 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
20610 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
20620 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
20630 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
20640 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
20650 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
20660 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
20670 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
20680 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20690 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
206a0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
206b0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
206c0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
206d0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
206e0 41 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ATE])..*/.int sq
206f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
20700 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
20710 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
20720 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
20730 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
20740 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
20750 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
20760 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
20770 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
20780 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
20790 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
207a0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
207b0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
207c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
207d0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
207e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
207f0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
20800 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
20810 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
20820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
20830 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
20840 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
20850 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
20860 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
20870 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
20880 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
20890 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
208a0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
208b0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
208c0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
208d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
208e0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
208f0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
20900 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
20910 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
20920 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
20930 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
20940 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
20950 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
20960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20970 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
20980 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
20990 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
209a0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
209b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
209c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
209d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
209e0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
209f0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
20a00 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
20a10 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
20a20 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
20a30 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
20a40 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
20a50 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
20a60 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
20a70 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
20a80 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
20a90 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
20aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
20ab0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
20ac0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
20ad0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
20ae0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
20af0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
20b00 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
20b10 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
20b20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
20b30 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
20b40 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
20b50 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
20b60 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
20b70 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
20b80 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
20b90 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
20ba0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
20bb0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
20bc0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
20bd0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
20be0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
20bf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20c00 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
20c10 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
20c20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
20c30 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
20c40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
20c50 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
20c60 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
20c70 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
20c80 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
20c90 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
20ca0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
20cb0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
20cc0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
20cd0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
20ce0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
20cf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
20d00 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
20d10 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
20d20 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
20d30 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
20d40 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
20d50 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
20d60 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
20d70 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
20d80 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
20d90 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
20da0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
20db0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
20dc0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
20dd0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
20de0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
20df0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
20e00 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
20e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
20e20 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
20e30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
20e40 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
20e50 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
20e60 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
20e70 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
20e80 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
20e90 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
20ea0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
20eb0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
20ec0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
20ed0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
20ee0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
20ef0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
20f00 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
20f10 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
20f20 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
20f30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20f40 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
20f50 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
20f60 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
20f70 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
20f80 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
20f90 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
20fa0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
20fb0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
20fc0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
20fd0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
20fe0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
20ff0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
21000 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
21010 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
21020 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
21030 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
21040 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
21050 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
21060 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
21070 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
21080 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
21090 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
210a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
210b0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
210c0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
210d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
210e0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
210f0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
21100 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
21110 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
21120 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
21130 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
21140 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
21150 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
21160 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
21170 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
21180 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
21190 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
211a0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
211b0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
211c0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
211d0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
211e0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
211f0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
21200 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
21210 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
21220 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
21230 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
21240 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
21250 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
21260 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
21270 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
21280 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
21290 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
212a0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
212b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
212c0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
212d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
212e0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
212f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
21300 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
21310 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
21320 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
21330 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
21340 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
21350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
21360 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
21370 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
21380 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
21390 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
213a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
213b0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
213c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
213d0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
213e0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
213f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
21400 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
21410 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
21420 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
21430 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21440 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21450 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
21460 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
21470 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21480 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
21490 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
214a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
214b0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
214c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
214d0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
214e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
214f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
21510 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
21520 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21530 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21540 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
21550 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
21560 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
21570 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
21580 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
21590 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
215a0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
215b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
215c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
215d0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
215e0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
215f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
21600 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
21610 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
21620 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
21630 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
21640 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
21650 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
21660 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
21670 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
21680 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
21690 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
216a0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
216b0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
216c0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
216d0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
216e0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
216f0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
21700 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21710 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
21720 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
21730 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
21740 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
21750 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
21760 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
21770 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
21780 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
21790 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
217a0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
217b0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
217c0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
217d0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
217e0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
217f0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
21800 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
21810 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
21820 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
21830 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
21840 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
21850 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
21860 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
21870 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
21880 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
21890 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
218a0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
218b0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
218c0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
218d0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
218e0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
218f0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
21900 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
21910 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
21920 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
21930 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
21940 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
21950 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
21960 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
21970 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
21980 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
21990 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
219a0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
219b0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
219c0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
219d0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
219e0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
219f0 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
21a00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
21a10 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
21a20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
21a30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
21a40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
21a50 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
21a60 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
21a70 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
21a80 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
21a90 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
21aa0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21ab0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
21ac0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
21ad0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
21ae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21af0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
21b00 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
21b10 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
21b20 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
21b30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21b40 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21b50 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
21b60 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
21b70 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
21b80 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
21b90 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
21ba0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
21bb0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
21bc0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
21bd0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
21be0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
21bf0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
21c00 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
21c10 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
21c20 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
21c30 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
21c40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21c50 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
21c60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21c70 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
21c80 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
21c90 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
21ca0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
21cb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
21cc0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
21cd0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
21ce0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
21cf0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
21d00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
21d10 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
21d20 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
21d30 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
21d40 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
21d50 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
21d60 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
21d70 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
21d80 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
21d90 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
21da0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
21db0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
21dc0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
21dd0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
21de0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
21df0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
21e00 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
21e10 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
21e20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21e30 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
21e40 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
21e50 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
21e60 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
21e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
21e80 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
21e90 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
21ea0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
21eb0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
21ec0 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
21ed0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
21ee0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
21ef0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
21f00 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
21f10 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
21f20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
21f30 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
21f40 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
21f50 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
21f60 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
21f70 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
21f80 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
21f90 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
21fa0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
21fb0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
21fc0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
21fd0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
21fe0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
21ff0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
22000 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
22010 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
22020 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
22030 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
22040 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
22050 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
22060 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
22070 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
22080 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22090 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
220a0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
220b0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
220c0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
220d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
220e0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
220f0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
22100 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
22110 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
22120 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
22130 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
22140 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
22150 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
22160 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
22170 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
22180 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
22190 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
221a0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
221b0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
221c0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
221d0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
221e0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
221f0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
22200 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
22210 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
22220 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
22230 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
22240 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
22250 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
22260 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
22270 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
22280 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
22290 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
222a0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
222b0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
222c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
222d0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
222e0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
222f0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
22300 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
22310 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
22320 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
22330 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
22340 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
22350 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
22360 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
22370 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
22380 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22390 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
223a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
223b0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
223c0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
223d0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
223e0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
223f0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
22400 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
22410 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
22420 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
22430 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
22440 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
22450 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
22460 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
22470 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
22480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22490 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
224a0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
224b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
224c0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
224d0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
224e0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
224f0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
22500 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
22510 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
22520 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
22530 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
22540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22550 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
22560 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
22570 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
22580 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
22590 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
225a0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
225b0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
225c0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
225d0 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71  23.1, it was req
225e0 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73  uired.** after s
225f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
22600 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20  turned anything 
22610 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
22620 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20  TE_ROW] that.** 
22630 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22640 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  ] be called befo
22650 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
22660 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
22670 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
22680 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69  ).  Failure to i
22690 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72  nvoke [sqlite3_r
226a0 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20  eset()] in this 
226b0 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73  way would.** res
226c0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
226d0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
226e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74   from sqlite3_st
226f0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
22700 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  .** version 3.6.
22710 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
22720 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69  ep() began calli
22730 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
22740 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74  t()] .** automat
22750 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
22760 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
22770 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  er than returnin
22780 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
22790 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ].  .**.** <b>Go
227a0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
227b0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
227c0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
227d0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
227e0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
227f0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
22800 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
22810 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
22820 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
22830 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
22840 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
22850 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
22860 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
22870 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
22880 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
22890 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
228a0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
228b0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
228c0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
228d0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
228e0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
228f0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
22900 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
22910 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
22920 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
22930 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
22940 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
22950 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
22960 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
22970 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
22980 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
22990 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
229a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
229b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
229c0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
229d0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
229e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
229f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
22a00 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
22a10 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
22a20 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
22a30 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
22a40 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
22a50 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
22a60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
22a70 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
22a80 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
22a90 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
22aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
22ab0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
22ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22ad0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
22ae0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
22af0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
22b00 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
22b10 6e 74 28 50 29 20 74 68 65 20 6e 75 6d 62 65 72  nt(P) the number
22b20 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
22b30 68 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  he.** of the res
22b40 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
22b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22b60 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  P..*/.int sqlite
22b70 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
22b80 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
22b90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22ba0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
22bb0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
22bc0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
22bd0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
22be0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
22bf0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
22c00 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
22c10 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
22c20 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
22c30 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
22c40 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
22c50 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
22c60 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
22c70 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
22c80 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
22c90 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
22ca0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
22cb0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
22cc0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
22cd0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
22ce0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
22cf0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
22d00 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
22d10 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
22d20 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
22d30 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
22d40 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
22d50 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
22d60 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
22d70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
22d80 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
22d90 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
22da0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
22db0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
22dc0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
22dd0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
22de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
22df0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
22e00 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
22e10 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
22e20 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
22e30 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
22e40 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
22e50 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
22e60 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
22e70 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
22e80 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
22e90 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
22ea0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
22eb0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
22ec0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
22ed0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
22ee0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
22ef0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
22f00 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
22f10 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
22f20 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
22f30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
22f40 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
22f50 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
22f60 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
22f70 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
22f80 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
22f90 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
22fa0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
22fb0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
22fc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22fd0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
22fe0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
22ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
23000 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
23010 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
23020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23030 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
23040 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
23050 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
23060 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
23070 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
23080 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
23090 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
230a0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
230b0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
230c0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
230d0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
230e0 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
230f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
23100 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
23110 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
23120 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
23130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
23140 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
23150 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
23160 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
23170 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
23180 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
23190 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
231a0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
231b0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
231c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
231d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
231e0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
231f0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
23200 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
23210 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
23220 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
23230 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
23240 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
23250 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
23260 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
23270 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
23280 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
23290 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
232a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
232b0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
232c0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
232d0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
232e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
232f0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
23300 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
23310 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
23320 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
23330 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
23340 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
23350 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
23360 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23370 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23380 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
23390 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
233a0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
233b0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
233c0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
233d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
233e0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
233f0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
23400 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23420 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
23430 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
23440 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
23450 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
23460 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
23470 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
23480 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
23490 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
234a0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
234b0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
234c0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
234d0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
234e0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
234f0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
23500 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
23510 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
23520 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
23530 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
23540 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
23550 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
23560 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
23570 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
23580 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
23590 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
235a0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
235b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
235c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
235d0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
235e0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
235f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23600 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
23610 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
23620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23630 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
23640 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
23650 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
23660 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
23670 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
23680 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
23690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
236a0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
236b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
236c0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
236d0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
236e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
236f0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
23700 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
23710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23720 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
23730 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
23740 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
23750 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
23760 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
23770 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
23780 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
23790 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
237a0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
237b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
237c0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
237d0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
237e0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
237f0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
23800 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
23810 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
23820 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
23830 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
23840 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
23850 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
23860 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
23870 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
23880 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
23890 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
238a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
238b0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
238c0 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
238d0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
238e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
238f0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
23900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23910 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
23920 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23930 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
23940 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
23950 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
23960 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
23970 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
23980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23990 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
239a0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
239b0 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
239c0 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
239d0 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
239e0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
239f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
23a00 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
23a10 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
23a20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23a30 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
23a40 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
23a50 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   in UTF-16 in na
23a60 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
23a70 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
23a80 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74  ..** ^The zero t
23a90 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
23aa0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
23ab0 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  s count..**.** ^
23ac0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
23ad0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
23ae0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
23af0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
23b00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23b10 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
23b20 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
23b30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23b40 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
23b50 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
23b60 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
23b70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
23b80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
23b90 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
23ba0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23bb0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
23bc0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
23bd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
23be0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
23bf0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
23c00 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
23c10 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
23c20 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
23c30 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
23c40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
23c50 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
23c60 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
23c70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
23c80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
23c90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23ca0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
23cb0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
23cc0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
23cd0 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
23ce0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
23cf0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
23d00 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
23d10 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
23d20 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
23d30 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
23d40 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
23d50 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
23d60 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
23d70 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
23d80 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
23d90 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
23da0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
23db0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
23dc0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
23dd0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
23de0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
23df0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
23e00 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
23e10 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
23e20 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
23e30 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
23e40 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
23e50 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
23e60 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
23e70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
23e80 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
23e90 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
23ea0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
23eb0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23ec0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23ed0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
23ee0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
23ef0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23f00 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
23f10 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
23f20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
23f30 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
23f40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
23f50 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
23f60 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
23f70 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
23f80 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
23f90 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
23fa0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
23fb0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
23fc0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
23fd0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
23fe0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
23ff0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
24000 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
24010 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
24020 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
24030 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
24040 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
24050 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
24060 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
24070 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
24080 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
24090 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
240a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
240b0 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
240c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
240d0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
240e0 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
240f0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
24100 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
24110 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
24120 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
24130 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
24140 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
24150 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
24160 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
24170 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
24180 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
24190 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
241a0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
241b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
241c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
241d0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
241e0 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
241f0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
24200 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
24210 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
24220 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
24230 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
24240 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
24250 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
24260 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
24270 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
24280 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
24290 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
242a0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
242b0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
242c0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
242d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
242e0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
242f0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
24300 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
24310 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
24320 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
24330 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
24340 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
24350 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
24360 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
24370 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
24380 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rammers..**.** ^
24390 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
243a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
243b0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
243c0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
243d0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
243e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
243f0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
24400 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
24410 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
24420 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
24430 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
24440 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76  ..** ^(Type conv
24450 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
24460 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
24470 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
24480 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
24490 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
244a0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
244b0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
244c0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
244d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
244e0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
244f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24500 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
24510 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
24520 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
24530 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
24540 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
24550 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
24560 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
24570 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
24580 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
24590 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
245a0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
245b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
245c0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
245d0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
245e0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
245f0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
24600 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
24610 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
24620 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
24630 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
24640 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
24650 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
24660 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
24670 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
24680 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
24690 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
246a0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
246b0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f  /ul>)^.**.** ^Co
246c0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
246d0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
246e0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
246f0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
24700 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
24710 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
24720 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
24730 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
24740 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
24750 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
24760 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
24770 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
24780 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
24790 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
247a0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
247b0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
247c0 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
247d0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
247e0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
247f0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
24800 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
24810 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
24820 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
24830 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61  ..**.** ^(The sa
24840 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
24850 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
24860 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
24870 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
24880 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
24890 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
248a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
248b0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
248c0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
248d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
248e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
248f0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
24900 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
24910 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
24920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24930 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
24940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24950 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
24960 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
24970 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
24980 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  >.** </ul>)^.**.
24990 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
249a0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
249b0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
249c0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
249d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
249e0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
249f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
24a00 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
24a10 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
24a20 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
24a30 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
24a40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24a50 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
24a60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24a70 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
24a80 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
24a90 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
24aa0 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
24ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24ac0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
24ad0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
24ae0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
24af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24b00 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
24b10 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
24b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24b30 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
24b40 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
24b50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
24b60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
24b70 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
24b80 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
24b90 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24ba0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
24bb0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
24bc0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
24bd0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
24be0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
24bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
24c00 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
24c10 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
24c20 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
24c30 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
24c40 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
24c50 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
24c60 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
24c70 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
24c80 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
24c90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24ca0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
24cb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
24cc0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
24cd0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
24ce0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
24cf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
24d00 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
24d10 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
24d20 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24d30 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
24d40 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
24d50 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
24d60 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
24d70 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
24d80 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
24d90 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
24da0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
24db0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
24dc0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
24dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
24de0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
24df0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
24e00 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
24e10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24e20 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
24e30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24e40 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
24e50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
24e60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24e70 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
24e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24e90 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
24ea0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
24eb0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
24ec0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
24ed0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24ee0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24ef0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
24f00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24f10 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
24f20 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
24f30 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
24f40 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24f50 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
24f60 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
24f70 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
24f80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24f90 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
24fa0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24fb0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
24fc0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24fd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24fe0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
24ff0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25000 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
25010 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
25020 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
25030 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25040 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25050 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
25060 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
25070 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
25080 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
25090 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
250a0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
250b0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
250c0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
250d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
250e0 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
250f0 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
25100 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
25110 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
25120 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
25130 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  ^If execution of
25140 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
25150 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
25160 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
25170 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
25180 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
25190 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ed..**.** ^This 
251a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
251b0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
251c0 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
251d0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
251e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
251f0 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65  ement].  ^If the
25200 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
25210 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
25220 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
25230 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
25240 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
25250 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
25260 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
25270 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
25280 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
25290 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e  terrupt]..** ^In
252a0 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
252b0 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
252c0 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
252d0 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
252e0 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
252f0 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
25300 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
25310 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
25320 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
25330 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e  TE_ABORT]..*/.in
25340 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
25350 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
25360 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
25370 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
25380 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
25390 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
253a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
253b0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
253c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
253d0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
253e0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
253f0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
25400 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
25410 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
25420 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
25430 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
25440 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
25450 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
25460 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
25470 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25480 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
25490 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
254a0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
254b0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
254c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
254d0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
254e0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
254f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
25500 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
25510 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
25520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25530 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
25540 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
25550 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
25560 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
25570 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
25580 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25590 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
255a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
255b0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
255c0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
255d0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
255e0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
255f0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
25600 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
25610 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
25620 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
25630 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
25640 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
25650 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
25660 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
25670 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
25680 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
25690 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
256a0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
256b0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
256c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
256d0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
256e0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
256f0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
25700 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25710 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
25720 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
25730 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
25740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25750 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
25760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25770 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
25780 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
25790 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
257a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
257b0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
257c0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
257d0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
257e0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
257f0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
25800 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
25810 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
25820 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25830 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
25840 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
25850 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25860 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
25870 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
25880 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
25890 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
258a0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
258b0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
258c0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
258d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
258e0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
258f0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
25900 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
25910 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
25920 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
25930 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
25940 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
25950 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
25960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25970 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
25980 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
25990 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
259a0 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
259b0 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
259c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
259d0 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
259e0 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
259f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25a00 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  16()..**.** ^The
25a10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
25a20 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
25a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
25a40 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
25a50 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
25a60 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
25a70 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
25a80 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
25a90 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
25aa0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
25ab0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25ac0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
25ad0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
25ae0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
25af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
25b00 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  arately..**.** T
25b10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25b20 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
25b30 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
25b40 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
25b50 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
25b60 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
25b70 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
25b80 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
25b90 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
25ba0 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65  f.** the zero-te
25bb0 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
25bc0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
25bd0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
25be0 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
25bf0 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79  haracters.  ^Any
25c00 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
25c10 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
25c20 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
25c30 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
25c40 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  in [SQLITE_ERROR
25c50 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
25c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
25c70 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
25c80 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
25c90 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25ca0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
25cb0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
25cc0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
25cd0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
25ce0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
25cf0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
25d00 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
25d10 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
25d20 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
25d30 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
25d40 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
25d50 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
25d60 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
25d70 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
25d80 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
25d90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
25da0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
25db0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
25dc0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25dd0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
25de0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
25df0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
25e00 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
25e10 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
25e20 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
25e30 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
25e40 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
25e50 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
25e60 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
25e70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
25e80 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
25e90 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
25ea0 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
25eb0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
25ec0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
25ed0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
25ee0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
25ef0 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
25f00 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
25f10 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
25f20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
25f30 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
25f40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25f50 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
25f60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25f70 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
25f80 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
25f90 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
25fa0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
25fb0 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
25fc0 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
25fd0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
25fe0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
25ff0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
26000 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
26010 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
26020 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
26030 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
26040 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
26050 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
26060 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
26070 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
26080 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
26090 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
260a0 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
260b0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
260c0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
260d0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
260e0 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
260f0 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
26100 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
26110 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
26120 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
26130 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
26140 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
26150 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
26160 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
26170 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
26180 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].)^.**.** The
26190 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
261a0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
261b0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
261c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
261d0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
261e0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
261f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
26200 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
26210 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
26220 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
26230 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
26240 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
26250 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
26260 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
26270 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
26280 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
26290 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
262a0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
262b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
262c0 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
262d0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
262e0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
262f0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
26300 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
26310 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
26320 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
26330 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
26340 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
26350 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
26360 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
26370 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
26380 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
26390 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  s..**.** ^It is 
263a0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
263b0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
263c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
263d0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
263e0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
263f0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
26400 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
26410 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
26420 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
26430 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
26440 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
26450 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
26460 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
26470 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
26480 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
26490 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
264a0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
264b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
264c0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
264d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
264e0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
264f0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
26500 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
26510 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
26520 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
26530 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
26540 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
26550 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
26560 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
26570 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
26580 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
26590 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
265a0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
265b0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
265c0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
265d0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
265e0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
265f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26600 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
26610 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
26620 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
26630 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
26640 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
26650 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
26660 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
26670 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
26680 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
26690 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
266a0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
266b0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
266c0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
266d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
266e0 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66  tions..** ^The f
266f0 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  irst application
26700 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26710 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e  n with a given n
26720 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c  ame overrides al
26730 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75  l.** built-in fu
26740 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73  nctions in the s
26750 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
26760 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74  nnection] with t
26770 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
26780 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70   ^Subsequent app
26790 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
267a0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68   functions of th
267b0 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79  e same name only
267c0 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72   override .** pr
267d0 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ior application-
267e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
267f0 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78  s that are an ex
26800 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68  act match for th
26810 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70  e.** number of p
26820 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72  arameters and pr
26830 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67  eferred encoding
26840 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
26850 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26860 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
26870 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
26880 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
26890 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
268a0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
268b0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
268c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
268d0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
268e0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
268f0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
26900 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
26910 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
26920 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
26930 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
26940 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
26950 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
26960 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
26970 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
26980 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
26990 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
269a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
269b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
269c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
269d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
269e0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
269f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
26a00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
26a10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
26a20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26a30 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
26a40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26a50 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
26a60 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
26a70 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
26a80 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
26a90 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
26aa0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
26ab0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
26ac0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
26ad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
26ae0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
26af0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26b00 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
26b10 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
26b20 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
26b30 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
26b40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
26b50 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
26b60 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
26b70 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
26b80 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
26b90 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
26ba0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
26bb0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
26bc0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
26bd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
26be0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
26bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26c00 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
26c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26c20 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
26c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26c40 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
26c50 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
26c60 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
26c70 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
26c80 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
26c90 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
26ca0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
26cb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26cc0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
26cd0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
26ce0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
26cf0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
26d00 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
26d10 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
26d20 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
26d30 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
26d40 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
26d50 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
26d60 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
26d70 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
26d80 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
26d90 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
26da0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
26db0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
26dc0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
26dd0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
26de0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
26df0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
26e00 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
26e10 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
26e20 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
26e30 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
26e40 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
26e50 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
26e60 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
26e70 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
26e80 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
26e90 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
26ea0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
26eb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26ec0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
26ed0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
26ee0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
26ef0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
26f00 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
26f10 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
26f20 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
26f30 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
26f40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
26f50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
26f60 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
26f70 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
26f80 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
26f90 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26fa0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
26fb0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
26fc0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
26fd0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
26fe0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
26ff0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
27000 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
27010 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
27020 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
27030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
27040 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
27050 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
27060 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
27070 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
27080 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
27090 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
270a0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
270b0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
270c0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
270d0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
270e0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
270f0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
27100 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
27110 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
27120 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
27130 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
27140 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
27150 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
27160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
27170 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
27180 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
27190 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
271a0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
271b0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
271c0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
271d0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
271e0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
271f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
27200 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
27210 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
27220 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
27230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27240 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
27250 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
27260 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27270 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
27280 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
27290 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
272a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
272b0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
272c0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
272d0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
272e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
272f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
27300 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
27310 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
27320 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27330 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
27340 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
27350 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
27360 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
27370 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
27380 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
27390 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
273a0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
273b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
273c0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
273d0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
273e0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
273f0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
27400 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
27410 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
27420 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
27430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
27440 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
27450 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
27460 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
27470 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
27480 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
27490 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
274a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
274b0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
274c0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
274d0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
274e0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
274f0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
27500 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
27510 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
27520 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
27530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27540 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
27550 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
27560 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
27570 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
27580 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
27590 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
275a0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
275b0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
275c0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
275d0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
275e0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
275f0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
27600 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
27610 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
27620 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
27630 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
27640 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
27650 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
27660 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
27670 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
27680 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
27690 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
276a0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
276b0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
276c0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
276d0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
276e0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
276f0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
27700 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
27710 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
27720 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
27730 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
27740 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
27750 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
27760 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
27770 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
27780 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
27790 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
277a0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
277b0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
277c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
277d0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
277e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
277f0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
27800 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27810 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
27820 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
27830 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
27840 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
27850 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
27860 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
27870 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
27880 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
27890 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
278a0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
278b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
278c0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
278d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
278e0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
278f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
27900 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
27910 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
27920 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
27930 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27940 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
27950 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27960 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27970 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
27980 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
27990 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
279a0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
279b0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
279c0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
279d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
279e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
279f0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
27a00 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
27a10 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
27a20 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
27a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
27a40 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
27a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27a60 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
27a70 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
27a80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27a90 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
27aa0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
27ab0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
27ac0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
27ad0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
27ae0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
27af0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
27b00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
27b10 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
27b20 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
27b30 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
27b40 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
27b50 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
27b60 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
27b70 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
27b80 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
27b90 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
27ba0 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20  mplementions of 
27bb0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
27bc0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
27bd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
27be0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
27bf0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
27c00 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
27c10 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
27c20 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
27c30 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
27c40 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
27c50 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
27c60 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
27c70 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
27c80 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
27c90 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
27ca0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
27cb0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
27cc0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
27cd0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
27ce0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
27cf0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
27d00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
27d10 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27d20 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
27d30 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
27d40 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
27d50 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
27d60 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
27d70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27d80 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
27d90 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
27da0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
27db0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
27dc0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
27dd0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
27de0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
27df0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
27e00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
27e10 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
27e20 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
27e30 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
27e40 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
27e50 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
27e60 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
27e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
27e80 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
27e90 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
27ea0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
27eb0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
27ec0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
27ed0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27ee0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
27ef0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
27f00 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
27f10 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
27f20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27f30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27f40 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
27f50 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
27f60 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
27f70 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
27f80 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
27f90 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
27fa0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
27fb0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
27fc0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
27fd0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
27fe0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27ff0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
28000 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
28010 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
28020 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
28030 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
28040 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
28050 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
28060 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
28070 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28080 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
28090 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
280a0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
280b0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
280c0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
280d0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
280e0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
280f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
28100 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
28110 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
28120 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28130 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
28140 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
28150 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
28160 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
28170 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
28180 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
28190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
281a0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
281b0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
281c0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
281d0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
281e0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
281f0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
28200 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
28210 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
28220 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
28230 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
28240 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
28250 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
28260 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
28270 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
28280 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
28290 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
282a0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
282b0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
282c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
282d0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
282e0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
282f0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
28300 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
28310 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
28320 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28330 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
28340 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
28350 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
28360 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
28370 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
28380 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
28390 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
283a0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
283b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
283c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
283d0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
283e0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
283f0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
28400 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
28410 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
28420 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
28430 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
28440 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
28450 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
28460 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28470 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
28480 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
28490 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
284a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
284b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
284c0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
284d0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
284e0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
284f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
28500 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
28510 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28520 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
28530 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
28540 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28550 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
28560 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
28570 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
28580 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
28590 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
285a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
285b0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
285c0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
285d0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
285e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
285f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
28600 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
28610 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
28620 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
28630 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
28640 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
28650 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
28660 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
28670 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
28680 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
28690 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
286a0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
286b0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
286c0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
286d0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
286e0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
286f0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
28700 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
28710 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
28720 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
28730 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
28740 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
28750 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
28760 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
28770 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
28780 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
28790 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
287a0 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
287b0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
287c0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
287d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
287e0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
287f0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
28800 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
28810 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
28820 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
28830 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
28840 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
28850 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
28860 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
28870 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
28880 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
28890 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
288a0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
288b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
288c0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
288d0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
288e0 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
288f0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
28900 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
28910 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
28920 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
28930 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
28940 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
28950 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
28960 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
28970 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
28980 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
28990 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
289a0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
289b0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
289c0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
289d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
289e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
289f0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
28a00 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
28a10 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
28a20 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
28a30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
28a40 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
28a50 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
28a60 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
28a70 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
28a80 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
28a90 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
28aa0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
28ab0 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
28ac0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
28ad0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
28ae0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
28af0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
28b00 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
28b10 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
28b20 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
28b30 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
28b40 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
28b50 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
28b60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28b70 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
28b80 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
28b90 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
28ba0 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
28bb0 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
28bc0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
28bd0 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
28be0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
28bf0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
28c00 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
28c10 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
28c20 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
28c30 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
28c40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
28c50 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
28c60 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
28c70 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
28c80 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
28c90 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
28ca0 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
28cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
28cc0 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
28cd0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
28ce0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
28cf0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
28d00 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
28d10 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
28d20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
28d30 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
28d40 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
28d50 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
28d60 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
28d70 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
28d80 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
28d90 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
28da0 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
28db0 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
28dc0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
28dd0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
28de0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
28df0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
28e00 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
28e10 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
28e20 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
28e30 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
28e40 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
28e50 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
28e60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
28e70 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
28e80 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
28e90 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
28ea0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
28eb0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
28ec0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
28ed0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28ee0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
28ef0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
28f00 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
28f10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
28f20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
28f30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
28f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
28f50 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
28f60 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
28f70 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
28f80 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
28f90 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
28fa0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
28fb0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
28fc0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
28fd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
28fe0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
28ff0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
29000 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
29010 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
29020 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
29030 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
29040 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
29050 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
29060 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
29070 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
29080 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
29090 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
290a0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
290b0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
290c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
290d0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
290e0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
290f0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
29100 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
29110 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
29120 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
29130 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
29140 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
29150 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
29160 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
29170 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
29180 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
29190 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
291a0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
291b0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
291c0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
291d0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
291e0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
291f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
29200 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
29210 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
29220 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
29230 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
29240 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
29250 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
29260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29270 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
29280 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
29290 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
292a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
292b0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
292c0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
292d0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
292e0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
292f0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
29300 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
29310 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29320 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
29330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29340 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
29350 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
29360 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
29370 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
29380 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
29390 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
293a0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
293b0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
293c0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
293d0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
293e0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
293f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29400 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
29410 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
29420 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
29430 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
29440 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
29450 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29460 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
29470 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
29480 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
29490 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
294a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
294b0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
294c0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
294d0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
294e0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
294f0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
29500 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
29510 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
29520 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
29530 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
29540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
29550 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
29560 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
29570 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
29580 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29590 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
295a0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
295b0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
295c0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
295d0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
295e0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
295f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
29600 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
29610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
29620 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
29630 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
29640 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
29650 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29660 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
29670 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
29680 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
29690 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
296a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
296b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
296c0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
296d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
296e0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
296f0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
29700 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
29710 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
29720 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
29730 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
29740 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
29750 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
29760 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
29770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29780 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
29790 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
297a0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
297b0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
297c0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
297d0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
297e0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
297f0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
29800 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
29810 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
29820 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
29830 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
29840 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
29850 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
29860 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
29870 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
29880 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
29890 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
298a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
298b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
298c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
298d0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
298e0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
298f0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
29900 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
29910 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
29920 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
29930 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
29940 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
29950 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
29960 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
29970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29980 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
29990 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
299a0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
299b0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
299c0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
299d0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
299e0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
299f0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
29a00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29a10 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
29a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29a30 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
29a40 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
29a50 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
29a60 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
29a70 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
29a80 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
29a90 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
29aa0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
29ab0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
29ac0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
29ad0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
29ae0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
29af0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29b00 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
29b10 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
29b20 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
29b30 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
29b40 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
29b50 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
29b60 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
29b70 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
29b80 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
29b90 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
29ba0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
29bb0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
29bc0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
29bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29be0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
29bf0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
29c00 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
29c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29c20 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
29c30 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
29c40 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
29c50 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
29c60 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
29c70 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
29c80 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
29c90 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
29ca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29cb0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
29cc0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
29cd0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
29ce0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
29cf0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
29d00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
29d10 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
29d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29d30 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
29d40 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
29d50 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
29d60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29d70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29d80 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
29d90 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
29da0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
29db0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
29dc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29dd0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
29de0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
29df0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
29e00 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
29e10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29e20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
29e30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
29e40 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
29e50 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
29e60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
29e70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29e80 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
29e90 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29ea0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
29eb0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
29ec0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29ed0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
29ee0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29ef0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
29f00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29f10 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
29f20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29f30 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
29f40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
29f50 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
29f60 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
29f70 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
29f80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29f90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29fa0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
29fb0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
29fc0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
29fd0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
29fe0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
29ff0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
2a000 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
2a010 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
2a020 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
2a030 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2a040 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2a050 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2a060 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2a070 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2a080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a090 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2a0a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2a0b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2a0c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a0d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2a0e0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2a0f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2a100 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2a110 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2a120 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
2a130 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2a140 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
2a150 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2a160 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2a170 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2a180 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2a190 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2a1a0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2a1b0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2a1c0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2a1d0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2a1e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2a1f0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
2a200 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a210 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
2a220 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
2a230 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2a240 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2a250 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2a260 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
2a270 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2a280 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
2a290 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2a2a0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
2a2b0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
2a2c0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
2a2d0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
2a2e0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
2a2f0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2a300 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2a310 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2a320 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2a330 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2a340 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2a350 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
2a360 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a370 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2a380 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2a390 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
2a3a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
2a3b0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
2a3c0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2a3d0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
2a3e0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2a3f0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
2a400 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
2a410 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
2a420 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
2a430 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
2a440 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2a450 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2a460 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2a470 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2a480 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2a490 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2a4a0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2a4b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2a4c0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2a4d0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2a4e0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
2a4f0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
2a500 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
2a510 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
2a520 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
2a530 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2a540 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
2a550 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
2a560 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2a570 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
2a580 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2a590 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2a5a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a5b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2a5c0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
2a5d0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2a5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a5f0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
2a600 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2a610 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
2a620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a630 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
2a640 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2a650 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2a660 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
2a670 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a680 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
2a690 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
2a6a0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
2a6b0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
2a6c0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
2a6d0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
2a6e0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
2a6f0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
2a700 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a710 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
2a720 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
2a730 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2a740 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a750 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
2a760 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
2a770 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
2a780 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a790 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
2a7a0 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
2a7b0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
2a7c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2a7d0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
2a7e0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
2a7f0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
2a800 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
2a810 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
2a820 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a830 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
2a840 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2a850 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
2a860 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
2a870 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2a880 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a890 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
2a8a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2a8b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2a8c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2a8d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a8e0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
2a8f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
2a900 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
2a910 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
2a920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a930 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2a940 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2a950 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2a960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a970 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2a980 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2a990 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2a9a0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2a9b0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2a9c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a9d0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
2a9e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2a9f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2aa00 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2aa10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2aa20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2aa30 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
2aa40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2aa50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2aa60 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
2aa70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2aa80 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
2aa90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2aaa0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
2aab0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2aac0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2aad0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2aae0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2aaf0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2ab00 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2ab10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ab20 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
2ab30 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2ab40 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2ab50 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2ab60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ab70 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
2ab80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2ab90 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2aba0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2abb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2abc0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
2abd0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2abe0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2abf0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2ac00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2ac10 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
2ac20 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
2ac30 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
2ac40 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2ac50 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2ac60 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
2ac70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ac80 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
2ac90 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
2aca0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2acb0 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
2acc0 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
2acd0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
2ace0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2acf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
2ad00 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
2ad10 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
2ad20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2ad30 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
2ad40 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
2ad50 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
2ad60 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
2ad70 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ad80 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
2ad90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ada0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
2adb0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
2adc0 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
2add0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ade0 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20  on16(). ^In all 
2adf0 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
2ae00 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
2ae10 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2ae20 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2ae30 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2ae40 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
2ae50 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
2ae60 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
2ae70 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
2ae80 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16LE], or [SQLIT
2ae90 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
2aea0 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
2aeb0 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
2aec0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
2aed0 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
2aee0 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
2aef0 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
2af00 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
2af10 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
2af20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
2af30 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2af40 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72  ly. ^The.** thir
2af50 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
2af60 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
2af70 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63  _UTF16] to indic
2af80 61 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75  ate that the rou
2af90 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20  tine.** expects 
2afa0 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55  pointers to be U
2afb0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e  TF-16 strings in
2afc0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2afd0 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a   order, or the.*
2afe0 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62  * argument can b
2aff0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
2b000 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a  ALIGNED] if the.
2b010 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
2b020 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
2b030 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
2b040 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
2b050 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74  * of UTF-16 in t
2b060 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
2b070 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  rder..**.** A po
2b080 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
2b090 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
2b0a0 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
2b0b0 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
2b0c0 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
2b0d0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
2b0e0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
2b0f0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
2b100 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2b110 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
2b120 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
2b130 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
2b140 5e 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61  ^Each time the a
2b150 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
2b160 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
2b170 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
2b180 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
2b190 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2b1a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
2b1b0 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
2b1c0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
2b1d0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
2b1e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b1f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2b200 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b210 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72  ()..**.** ^The r
2b220 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
2b230 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ts to the applic
2b240 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72  ation-supplied r
2b250 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
2b260 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
2b270 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2b280 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20   (length, data) 
2b290 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
2b2a0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
2b2b0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
2b2c0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
2b2d0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
2b2e0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
2b2f0 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
2b300 69 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70  istered.  The ap
2b310 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2b320 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
2b330 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
2b340 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
2b350 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
2b360 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
2b370 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2b380 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f  ,.** equal to, o
2b390 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2b3a0 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67  he second string
2b3b0 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
2b3c0 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
2b3d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2b3e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2b3f0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
2b400 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b410 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78  ollation().** ex
2b420 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b  cept that it tak
2b430 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75  es an extra argu
2b440 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2b450 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a  destructor for.*
2b460 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e  * the collation.
2b470 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2b480 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
2b490 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
2b4a0 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
2b4b0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
2b4c0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
2b4d0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
2b4e0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
2b4f0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
2b500 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2b510 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
2b520 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
2b530 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
2b540 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
2b550 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  r calls to the.*
2b560 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  * collation crea
2b570 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
2b580 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61  r when the [data
2b590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b5a0 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73   is closed.** us
2b5b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2b5c0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  se()]..**.** See
2b5d0 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
2b5e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b5f0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
2b600 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b610 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
2b620 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b630 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
2b640 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2b650 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2b660 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2b670 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2b680 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2b690 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2b6a0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2b6b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2b6c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2b6d0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
2b6e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2b6f0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2b700 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2b710 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2b720 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2b730 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2b740 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
2b750 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
2b760 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2b770 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b780 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
2b790 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
2b7a0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
2b7b0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2b7c0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2b7d0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2b7e0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2b7f0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
2b800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2b810 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
2b820 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2b830 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
2b840 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
2b850 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b860 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
2b870 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
2b880 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
2b890 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2b8a0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
2b8b0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
2b8c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b8d0 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
2b8e0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
2b8f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2b900 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
2b910 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2b920 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
2b930 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
2b940 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2b950 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b960 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
2b970 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
2b980 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
2b990 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
2b9a0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
2b9b0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
2b9c0 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
2b9d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2b9e0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
2b9f0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
2ba00 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
2ba10 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
2ba20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2ba30 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
2ba40 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
2ba50 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
2ba60 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
2ba70 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
2ba80 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
2ba90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2baa0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
2bab0 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
2bac0 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
2bad0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
2bae0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2baf0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2bb00 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
2bb10 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2bb20 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
2bb30 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2bb40 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2bb50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
2bb60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2bb70 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2bb80 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2bb90 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
2bba0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2bbb0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
2bbc0 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
2bbd0 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
2bbe0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2bbf0 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
2bc00 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
2bc10 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2bc20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
2bc30 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
2bc40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
2bc50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
2bc60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
2bc70 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
2bc80 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
2bc90 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
2bca0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bcb0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
2bcc0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2bcd0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
2bce0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2bcf0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
2bd00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bd10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2bd20 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
2bd30 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
2bd40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2bd50 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
2bd60 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
2bd70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2bd80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
2bd90 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2bda0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
2bdb0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
2bdc0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
2bdd0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
2bde0 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
2bdf0 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
2be00 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
2be10 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
2be20 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
2be30 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
2be40 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
2be50 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
2be60 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
2be70 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2be80 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2be90 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2bea0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2beb0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2bec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
2bed0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2bee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bef0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2bf00 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2bf10 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2bf20 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2bf30 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
2bf40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
2bf50 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
2bf60 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
2bf70 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
2bf80 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
2bf90 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
2bfa0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
2bfb0 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
2bfc0 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
2bfd0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2bfe0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
2bff0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2c000 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2c010 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2c020 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2c030 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2c040 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2c050 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
2c060 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c080 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2c090 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2c0a0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2c0b0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2c0c0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
2c0d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2c0e0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2c0f0 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
2c100 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
2c110 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
2c120 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
2c130 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2c140 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2c150 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
2c160 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2c170 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2c180 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2c190 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2c1a0 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
2c1b0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
2c1c0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2c1d0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2c1e0 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
2c1f0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2c200 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2c210 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
2c220 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
2c230 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
2c240 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
2c250 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
2c260 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2c270 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2c280 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2c290 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2c2a0 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
2c2b0 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
2c2c0 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
2c2d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2c2e0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
2c2f0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
2c300 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
2c310 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
2c320 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
2c330 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2c340 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
2c350 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
2c360 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
2c370 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2c380 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
2c390 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
2c3a0 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
2c3b0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
2c3c0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
2c3d0 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
2c3e0 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
2c3f0 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
2c400 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  d. ^The number o
2c410 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
2c420 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2c430 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
2c440 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2c450 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
2c460 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
2c470 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2c480 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2c490 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2c4a0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2c4b0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2c4c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2c4d0 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ct..*/.int sqlit
2c4e0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
2c4f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c500 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
2c510 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
2c520 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
2c530 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
2c540 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
2c550 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
2c560 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2c570 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2c580 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
2c590 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
2c5a0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
2c5b0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
2c5c0 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
2c5d0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
2c5e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
2c5f0 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
2c600 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
2c610 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
2c620 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
2c630 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
2c640 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
2c650 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
2c660 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
2c670 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
2c680 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
2c690 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
2c6a0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
2c6b0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
2c6c0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
2c6d0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
2c6e0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
2c6f0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2c700 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2c710 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2c720 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
2c730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
2c740 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
2c750 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
2c760 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
2c770 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
2c780 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
2c790 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
2c7a0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
2c7b0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
2c7c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
2c7d0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
2c7e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
2c7f0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
2c800 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
2c810 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
2c820 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
2c830 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
2c840 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
2c850 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2c860 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
2c870 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
2c880 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
2c890 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
2c8a0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2c8b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c8c0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
2c8d0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
2c8e0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2c8f0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
2c900 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
2c910 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
2c920 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
2c930 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
2c940 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2c950 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
2c960 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
2c970 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
2c980 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
2c990 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
2c9a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
2c9b0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
2c9c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
2c9d0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
2c9e0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
2c9f0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
2ca00 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
2ca10 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2ca20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2ca30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
2ca40 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
2ca50 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
2ca60 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2ca70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
2ca80 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
2ca90 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
2caa0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
2cab0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
2cac0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
2cad0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
2cae0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
2caf0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
2cb00 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
2cb10 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
2cb20 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
2cb30 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2cb40 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
2cb50 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
2cb60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2cb70 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
2cb80 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
2cb90 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
2cba0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2cbb0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
2cbc0 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
2cbd0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
2cbe0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
2cbf0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2cc00 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2cc10 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
2cc20 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
2cc30 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
2cc40 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
2cc50 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
2cc60 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
2cc70 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
2cc80 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
2cc90 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
2cca0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
2ccb0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
2ccc0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
2ccd0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
2cce0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
2ccf0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
2cd00 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
2cd10 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
2cd20 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
2cd30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2cd40 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
2cd50 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
2cd60 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
2cd70 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd80 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
2cd90 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
2cda0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
2cdb0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
2cdc0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
2cdd0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
2cde0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
2cdf0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
2ce00 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2ce10 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
2ce20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
2ce30 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
2ce40 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
2ce50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
2ce60 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
2ce70 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
2ce80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2ce90 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
2cea0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
2ceb0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2cec0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
2ced0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
2cee0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
2cef0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
2cf00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
2cf10 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
2cf20 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
2cf30 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
2cf40 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
2cf50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2cf60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2cf70 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
2cf80 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
2cf90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cfa0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
2cfb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2cfc0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2cfd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2cfe0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
2cff0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
2d000 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
2d010 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2d020 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2d030 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
2d040 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
2d050 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2d060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d070 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
2d080 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2d090 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
2d0a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d0b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d0c0 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
2d0d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
2d0e0 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
2d0f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2d100 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d110 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
2d120 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
2d130 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
2d140 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2d150 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2d160 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
2d170 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
2d180 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
2d190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d1a0 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
2d1b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d1c0 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
2d1d0 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
2d1e0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
2d1f0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
2d200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
2d210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d220 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
2d230 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d240 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
2d250 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
2d260 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
2d270 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2d280 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
2d290 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
2d2a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2d2b0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
2d2c0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2d2d0 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
2d2e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d2f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d300 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
2d310 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
2d320 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2d330 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2d340 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2d350 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2d360 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2d370 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
2d380 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2d390 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
2d3a0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
2d3b0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
2d3c0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2d3d0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2d3e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
2d3f0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
2d400 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d420 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d430 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d440 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
2d450 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2d460 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2d470 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2d480 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2d490 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2d4a0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
2d4b0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
2d4c0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
2d4d0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2d4e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2d4f0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
2d500 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2d510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d520 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2d530 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
2d540 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
2d550 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
2d560 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
2d570 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
2d580 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
2d590 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
2d5a0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
2d5b0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
2d5c0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2d5d0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
2d5e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d5f0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
2d600 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
2d610 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
2d620 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
2d630 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
2d640 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
2d650 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
2d660 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2d670 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
2d680 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d690 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
2d6a0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
2d6b0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
2d6c0 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
2d6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2d6e0 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
2d6f0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
2d700 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
2d710 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
2d720 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d730 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
2d740 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
2d750 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2d760 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2d770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d780 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2d790 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2d7a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2d7b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d7c0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2d7d0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2d7e0 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
2d7f0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
2d800 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2d810 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
2d820 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d830 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2d840 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
2d850 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
2d860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d870 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
2d880 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
2d890 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
2d8a0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
2d8b0 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
2d8c0 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
2d8d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2d8e0 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
2d8f0 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
2d900 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d910 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
2d920 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
2d930 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
2d940 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
2d950 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
2d960 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
2d970 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
2d980 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
2d990 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
2d9a0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
2d9b0 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
2d9c0 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
2d9d0 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
2d9e0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
2d9f0 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
2da00 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
2da10 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
2da20 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
2da30 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
2da40 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
2da50 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
2da60 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
2da70 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
2da80 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
2da90 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
2daa0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
2dab0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
2dac0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
2dad0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
2dae0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
2daf0 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
2db00 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
2db10 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
2db20 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
2db30 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
2db40 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
2db50 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2db60 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
2db70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2db80 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
2db90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2dba0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2dbb0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2dbc0 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
2dbd0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2dbe0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
2dbf0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
2dc00 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
2dc10 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2dc20 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
2dc30 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
2dc40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dc50 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
2dc60 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2dc70 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
2dc80 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2dc90 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2dca0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2dcb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
2dcc0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2dcd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dce0 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
2dcf0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2dd00 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
2dd10 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
2dd20 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2dd30 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2dd40 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
2dd50 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2dd60 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
2dd70 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2dd80 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2dd90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dda0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2ddb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2ddc0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2ddd0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2dde0 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2ddf0 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2de00 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2de10 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2de20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2de30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2de40 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
2de50 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2de60 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2de70 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2de80 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
2de90 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
2dea0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2deb0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
2dec0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
2ded0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2dee0 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
2def0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
2df00 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
2df10 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
2df20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
2df30 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
2df40 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2df50 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
2df60 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
2df70 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
2df80 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
2df90 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
2dfa0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
2dfb0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
2dfc0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
2dfd0 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
2dfe0 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
2dff0 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
2e000 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2e010 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2e020 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2e030 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2e040 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
2e050 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
2e060 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
2e070 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
2e080 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
2e090 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
2e0a0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
2e0b0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
2e0c0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
2e0d0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2e0e0 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2e0f0 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2e100 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2e110 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2e120 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2e130 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2e140 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2e150 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2e160 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
2e170 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2e180 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
2e190 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
2e1a0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
2e1b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
2e1c0 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
2e1d0 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
2e1e0 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
2e1f0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
2e200 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
2e210 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2e220 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2e230 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2e240 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2e250 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2e260 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2e270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e280 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2e290 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2e2a0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2e2b0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2e2c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e2d0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2e2e0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2e2f0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2e300 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2e310 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2e320 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2e330 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2e340 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2e350 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2e360 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2e370 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2e380 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2e390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2e3a0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2e3b0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2e3c0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2e3d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e3e0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
2e3f0 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
2e400 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
2e410 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2e420 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
2e430 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2e440 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e450 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2e460 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2e470 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
2e480 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2e490 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2e4a0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
2e4b0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2e4c0 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
2e4d0 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
2e4e0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2e4f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2e500 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
2e510 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
2e520 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
2e530 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
2e540 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
2e550 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2e560 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
2e570 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
2e580 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2e590 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
2e5a0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2e5b0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
2e5c0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
2e5d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2e5e0 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
2e5f0 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
2e600 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
2e610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e620 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
2e630 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2e640 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
2e650 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
2e660 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2e670 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
2e680 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2e690 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
2e6a0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
2e6b0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2e6c0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
2e6d0 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
2e6e0 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
2e6f0 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
2e700 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
2e710 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
2e720 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2e730 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
2e740 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2e750 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
2e760 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
2e770 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
2e780 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
2e790 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
2e7a0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
2e7b0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
2e7c0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e7d0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2e7e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2e7f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
2e800 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
2e810 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
2e820 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
2e830 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
2e840 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
2e850 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
2e860 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
2e870 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
2e880 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2e890 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
2e8a0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
2e8b0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
2e8c0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
2e8d0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2e8e0 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
2e8f0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
2e900 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
2e910 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2e920 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2e930 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2e940 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2e950 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2e960 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2e970 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2e980 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2e990 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2e9a0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2e9b0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2e9c0 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2e9d0 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2e9e0 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
2e9f0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2ea00 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
2ea10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ea20 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
2ea30 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
2ea40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ea50 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2ea60 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2ea70 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
2ea80 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
2ea90 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
2eaa0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
2eab0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
2eac0 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
2ead0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2eae0 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
2eaf0 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
2eb00 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
2eb10 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
2eb20 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
2eb30 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
2eb40 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
2eb50 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
2eb60 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
2eb70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2eb80 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
2eb90 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
2eba0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
2ebb0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
2ebc0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
2ebd0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2ebe0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2ebf0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2ec00 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
2ec10 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
2ec20 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
2ec30 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2ec40 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
2ec50 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
2ec60 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
2ec70 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
2ec80 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
2ec90 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
2eca0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66  y SQLite..** ^If
2ecb0 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c   an internal all
2ecc0 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  ocation is reque
2ecd0 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20  sted that would 
2ece0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f  exceed the.** so
2ecf0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b  ft heap limit, [
2ed00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2ed10 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76  memory()] is inv
2ed20 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d  oked one or.** m
2ed30 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
2ed40 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
2ed50 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
2ed60 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  ation is perform
2ed70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c  ed..**.** ^The l
2ed80 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2ed90 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66  soft" because if
2eda0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2edb0 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63  e_memory()].** c
2edc0 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69  annot free suffi
2edd0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
2ede0 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
2edf0 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
2ee00 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65  eeded,.** the me
2ee10 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
2ee20 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
2ee30 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
2ee40 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
2ee50 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f  ** ^A negative o
2ee60 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2ee70 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2ee80 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2ee90 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2eea0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2eeb0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2eec0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2eed0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2eee0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  xhausted..** ^Th
2eef0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2ef00 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2ef10 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2ef20 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
2ef30 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
2ef40 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
2ef50 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2ef60 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20  ..** But if the 
2ef70 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2ef80 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65  cannot be honore
2ef90 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
2efa0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
2efb0 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
2efc0 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20  otification.)^  
2efd0 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
2efe0 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  limit is.** call
2eff0 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
2f000 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
2f010 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
2f020 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
2f030 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2f040 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
2f050 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
2f060 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
2f070 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
2f080 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
2f090 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2f0a0 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
2f0b0 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
2f0c0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
2f0d0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2f0e0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2f0f0 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
2f100 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
2f110 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
2f120 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
2f130 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
2f140 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
2f150 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
2f160 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2f170 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
2f180 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
2f190 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
2f1a0 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
2f1b0 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
2f1c0 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
2f1d0 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
2f1e0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2f1f0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2f200 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
2f210 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
2f220 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
2f230 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
2f240 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
2f250 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f260 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
2f270 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
2f280 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
2f290 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
2f2a0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
2f2b0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
2f2c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2f2d0 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
2f2e0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
2f2f0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2f300 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
2f310 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
2f320 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
2f330 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
2f340 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
2f350 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
2f360 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f370 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
2f380 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2f390 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
2f3a0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
2f3b0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
2f3c0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
2f3d0 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
2f3e0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
2f3f0 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
2f400 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
2f410 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
2f420 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
2f430 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
2f440 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
2f450 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
2f460 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2f470 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
2f480 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
2f490 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
2f4a0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2f4b0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2f4c0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2f4d0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
2f4e0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
2f4f0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
2f500 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
2f510 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
2f520 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
2f530 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
2f540 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
2f550 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
2f560 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
2f570 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
2f580 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
2f590 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
2f5a0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
2f5b0 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
2f5c0 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
2f5d0 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
2f5e0 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
2f5f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2f600 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2f610 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
2f620 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
2f630 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
2f640 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2f650 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2f660 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2f670 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2f680 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2f690 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2f6a0 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2f6b0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2f6c0 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2f6d0 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2f6e0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2f6f0 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2f700 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2f710 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2f720 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2f730 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2f740 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2f750 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2f760 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2f770 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2f780 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2f790 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2f7a0 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2f7b0 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2f7c0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2f7d0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2f7e0 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2f7f0 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2f800 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2f810 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
2f820 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
2f830 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
2f840 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
2f850 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
2f860 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
2f870 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
2f880 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
2f890 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
2f8a0 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
2f8b0 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
2f8c0 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
2f8d0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2f8e0 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
2f8f0 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
2f900 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2f910 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2f920 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2f930 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2f940 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2f950 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2f960 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
2f970 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2f980 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
2f990 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
2f9a0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2f9b0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2f9c0 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2f9d0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2f9e0 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
2f9f0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
2fa00 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2fa10 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2fa20 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
2fa30 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2fa40 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2fa50 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
2fa60 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
2fa70 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
2fa80 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
2fa90 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2faa0 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
2fab0 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
2fac0 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
2fad0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
2fae0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
2faf0 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
2fb00 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
2fb10 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
2fb20 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
2fb30 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
2fb40 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
2fb50 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2fb60 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
2fb70 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
2fb80 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
2fb90 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
2fba0 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
2fbb0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2fbc0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
2fbd0 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
2fbe0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2fbf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
2fc00 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
2fc10 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
2fc20 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
2fc30 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
2fc40 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2fc50 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2fc60 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2fc70 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2fc80 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2fc90 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2fca0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
2fcb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fcc0 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
2fcd0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
2fce0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2fcf0 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
2fd00 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
2fd10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
2fd20 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
2fd30 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
2fd40 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
2fd50 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
2fd60 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
2fd70 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
2fd80 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
2fd90 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
2fda0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
2fdb0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
2fdc0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
2fdd0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
2fde0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2fdf0 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
2fe00 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
2fe10 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2fe20 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
2fe30 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
2fe40 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2fe50 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
2fe60 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
2fe70 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
2fe80 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
2fe90 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2fea0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2feb0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
2fec0 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
2fed0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2fee0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
2fef0 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
2ff00 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
2ff10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
2ff20 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
2ff30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2ff40 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
2ff50 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2ff60 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
2ff70 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
2ff80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ff90 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2ffa0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2ffb0 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
2ffc0 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ** SQLite extens
2ffd0 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
2ffe0 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
2fff0 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  e zFile..**.** ^
30000 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
30010 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50  is zProc..** ^zP
30020 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e  roc may be 0, in
30030 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
30040 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
30050 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75  y point.** defau
30060 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
30070 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
30080 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30090 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
300a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
300b0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  rns.** [SQLITE_O
300c0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
300d0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
300e0 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
300f0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66  es wrong..** ^If
30100 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
30110 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
30120 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
30130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
30140 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
30150 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
30160 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c  ttempt to.** fil
30170 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
30180 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
30190 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
301a0 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
301b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
301c0 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61  alloc()]. The ca
301d0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
301e0 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  * should free th
301f0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
30200 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
30210 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  ee()]..**.** ^Ex
30220 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
30230 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
30240 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
30250 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
30260 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
30270 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
30280 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69   API,.** otherwi
30290 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
302a0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   be returned..**
302b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
302c0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
302d0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
302e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
302f0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
30300 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
30310 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
30320 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
30330 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
30340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
30350 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
30360 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
30370 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
30380 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
30390 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
303a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
303b0 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
303c0 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
303d0 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
303e0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
303f0 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
30400 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
30410 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
30420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30430 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
30440 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
30450 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53  Loading.**.** ^S
30460 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
30470 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
30480 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
30490 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
304a0 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
304b0 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
304c0 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
304d0 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
304e0 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
304f0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
30500 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
30510 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
30520 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
30530 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
30540 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
30550 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
30560 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
30570 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
30580 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
30590 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
305a0 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
305b0 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20  icket #1863..** 
305c0 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65  ^Call the sqlite
305d0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
305e0 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
305f0 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
30600 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  ** to turn exten
30610 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
30620 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
30630 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
30640 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66  n.** it back off
30650 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
30660 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
30670 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
30680 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
30690 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
306a0 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
306b0 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
306c0 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
306d0 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69  his API can be i
306e0 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61  nvoked at progra
306f0 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64  m startup in ord
30700 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  er to register.*
30710 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74  * one or more st
30720 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
30730 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20  extensions that 
30740 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c  will be availabl
30750 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20  e.** to all new 
30760 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30770 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tions]..**.** ^(
30780 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
30790 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
307a0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65   the extension e
307b0 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e  ntry point.** in
307c0 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69   an array that i
307d0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
307e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
307f0 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79  )].  That memory
30800 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74  .** is deallocat
30810 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72  ed by [sqlite3_r
30820 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
30830 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ion()].)^.**.** 
30840 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
30850 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
30860 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
30870 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74  t that is.** aut
30880 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
30890 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ed whenever a ne
308a0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
308b0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70  ection].** is op
308c0 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ened using [sqli
308d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
308e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
308f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
30900 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  open_v2()]..** ^
30910 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
30920 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
30930 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
30940 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c  s routine.** mul
30950 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
30960 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
30970 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
30980 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65  .** ^Automatic e
30990 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
309a0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
309b0 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
309c0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
309d0 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
309e0 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
309f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
30a00 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
30a10 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
30a20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
30a30 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
30a40 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
30a50 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
30a60 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
30a70 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65  s. It undoes the
30a80 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70   effect of all p
30a90 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rior.** [sqlite3
30aa0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
30ab0 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a  )] calls.)^.**.*
30ac0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
30ad0 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61   disables automa
30ae0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
30af0 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
30b00 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
30b10 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
30b20 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
30b30 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
30b40 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
30b50 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
30b60 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
30b70 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
30b80 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
30b90 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
30ba0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
30bb0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
30bc0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
30bd0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
30be0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
30bf0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
30c00 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
30c10 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
30c20 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
30c30 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
30c40 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
30c50 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
30c60 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
30c70 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
30c80 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
30c90 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
30ca0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
30cb0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
30cc0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
30cd0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30ce0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
30cf0 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
30d00 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30d10 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
30d20 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
30d30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30d40 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
30d50 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
30d60 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
30d70 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
30d80 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
30d90 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
30da0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
30db0 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
30dc0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
30dd0 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
30de0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
30df0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
30e00 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
30e10 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74  called a a "virt
30e20 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
30e30 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74  ", .** defines t
30e40 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
30e50 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  n of a [virtual 
30e60 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68  tables].  .** Th
30e70 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
30e80 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20  sists mostly of 
30e90 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
30ea0 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41  module..**.** ^A
30eb0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
30ec0 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64  odule is created
30ed0 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61   by filling in a
30ee0 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69   persistent.** i
30ef0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
30f00 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61  structure and pa
30f10 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20  ssing a pointer 
30f20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65  to that instance
30f30 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
30f40 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
30f50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
30f60 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
30f70 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74  ..** ^The regist
30f80 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
30f90 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
30fa0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
30fb0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
30fc0 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
30fd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30fe0 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
30ff0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
31000 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
31010 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
31020 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
31030 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
31040 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
31050 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
31060 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
31070 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
31080 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
31090 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
310a0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
310b0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
310c0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
310d0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
310e0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
310f0 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
31100 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
31110 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
31120 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
31130 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
31140 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
31150 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
31160 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
31170 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
31180 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
31190 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
311a0 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
311b0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
311c0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
311d0 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
311e0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
311f0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
31200 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
31210 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31220 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
31230 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
31240 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
31250 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
31260 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
31270 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
31280 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
31290 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
312a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
312b0 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
312c0 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
312d0 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
312e0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
312f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
31300 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
31310 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
31320 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
31330 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
31340 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
31350 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
31360 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
31370 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
31380 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
31390 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
313a0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
313b0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
313c0 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
313d0 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
313e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
313f0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
31400 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
31410 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
31420 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
31430 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
31440 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
31450 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
31460 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
31470 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
31480 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
31490 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
314a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
314b0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
314c0 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
314d0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
314e0 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
314f0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
31500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31510 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
31520 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
31530 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31540 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
31550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31560 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
31570 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
31580 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
31590 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
315a0 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
315b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
315c0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
315d0 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
315e0 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  n.** KEYWORDS: s
315f0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
31600 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
31610 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
31620 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
31630 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
31640 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73  s used to.** pas
31650 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
31660 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74  to and receive t
31670 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68  he reply from th
31680 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a  e [xBestIndex].*
31690 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76  * method of a [v
316a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
316b0 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64  ule].  The field
316c0 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
316d0 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
316e0 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
316f0 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
31700 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
31710 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
31720 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
31730 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
31740 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  elds..**.** ^(Th
31750 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
31760 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
31770 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
31780 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
31790 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63  rm:.**.** <pre>c
317a0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70  olumn OP expr</p
317b0 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  re>.**.** where 
317c0 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
317d0 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
317e0 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70  gt;=.)^  ^(The p
317f0 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74  articular operat
31800 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20  or is.** stored 
31810 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  in aConstraint[]
31820 2e 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e  .op.)^  ^(The in
31830 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
31840 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
31850 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
31860 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43  iColumn.)^  ^(aC
31870 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
31880 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
31890 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
318a0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
318b0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
318c0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
318d0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
318e0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
318f0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
31900 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70  )^.**.** ^The op
31910 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
31920 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
31930 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
31940 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
31950 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
31960 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
31970 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
31980 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
31990 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
319a0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
319b0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
319c0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
319d0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
319e0 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74  ..** ^The aConst
319f0 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
31a00 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
31a10 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68   clause terms th
31a20 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61  at are.** releva
31a30 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  nt to the partic
31a40 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
31a50 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
31a60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61  ..**.** ^Informa
31a70 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
31a80 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
31a90 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
31aa0 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68  erBy[]..** ^Each
31ab0 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42   term of aOrderB
31ac0 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75  y records a colu
31ad0 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20  mn of the ORDER 
31ae0 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a  BY clause..**.**
31af0 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   The [xBestIndex
31b00 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  ] method must fi
31b10 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
31b20 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
31b30 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
31b40 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
31b50 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
31b60 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64  er.  ^If argvInd
31b70 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
31b80 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
31b90 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
31ba0 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
31bb0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
31bc0 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
31bd0 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
31be0 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
31bf0 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e   ^(If aConstrain
31c00 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
31c10 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
31c20 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
31c30 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
31c40 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
31c50 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
31c60 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
31c70 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
31c80 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a   SQLite.)^.**.**
31c90 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64   ^The idxNum and
31ca0 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
31cb0 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
31cc0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
31cd0 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
31ce0 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65  hod..** ^[sqlite
31cf0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
31d00 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
31d10 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
31d20 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  ** needToFreeIdx
31d30 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
31d40 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43  ** ^The orderByC
31d50 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
31d60 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b  at output from [
31d70 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d  xFilter]/[xNext]
31d80 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
31d90 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
31da0 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
31db0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
31dc0 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
31dd0 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
31de0 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
31df0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  ed..**.** ^The e
31e00 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c  stimatedCost val
31e10 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ue is an estimat
31e20 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66  e of the cost of
31e30 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61   doing the.** pa
31e40 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e  rticular lookup.
31e50 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66    A full scan of
31e60 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20   a table with N 
31e70 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
31e80 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66  ave.** a cost of
31e90 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65   N.  A binary se
31ea0 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20  arch of a table 
31eb0 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  of N entries sho
31ec0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f  uld have a.** co
31ed0 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74  st of approximat
31ee0 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73  ely log(N)..*/.s
31ef0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
31f00 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20  dex_info {.  /* 
31f10 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20  Inputs */.  int 
31f20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
31f30 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
31f40 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61   of entries in a
31f50 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  Constraint */.  
31f60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
31f70 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
31f80 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
31f90 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
31fa0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
31fb0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
31fc0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
31fd0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
31fe0 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
31ff0 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
32000 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
32010 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
32020 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
32030 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
32040 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
32050 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
32060 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
32070 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
32080 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
32090 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
320a0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20  } *aConstraint; 
320b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61             /* Ta
320c0 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
320d0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
320e0 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42  */.  int nOrderB
320f0 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
32100 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
32110 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
32120 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73  BY clause */.  s
32130 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
32140 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20  dex_orderby {.  
32150 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
32160 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32170 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f  Column number */
32180 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
32190 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20  har desc;       
321a0 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43  /* True for DESC
321b0 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43  .  False for ASC
321c0 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72  . */.  } *aOrder
321d0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
321e0 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
321f0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a  Y clause */.  /*
32200 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
32210 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
32220 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
32230 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
32240 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
32250 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
32260 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
32270 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
32280 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
32290 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
322a0 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
322b0 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
322c0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
322d0 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
322e0 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
322f0 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
32300 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
32310 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
32320 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
32330 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
32340 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
32350 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
32360 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
32370 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
32380 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
32390 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
323a0 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
323b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
323c0 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
323d0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
323e0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
323f0 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
32400 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
32410 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
32420 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
32430 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
32440 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
32450 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
32460 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
32470 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
32480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
32490 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
324a0 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
324b0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
324c0 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
324d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
324e0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
324f0 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
32500 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
32510 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
32520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32530 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
32540 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
32550 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
32560 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
32570 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
32580 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
32590 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
325a0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
325b0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
325c0 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e  le module] name.
325d0 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65  .** ^Module name
325e0 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
325f0 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
32600 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
32610 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
32620 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ing the module a
32630 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  nd before using 
32640 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
32650 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
32660 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
32670 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75  .**.** ^The modu
32680 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73  le name is regis
32690 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61  tered on the [da
326a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
326b0 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  n] specified.** 
326c0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
326d0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61  ameter.  ^The na
326e0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
326f0 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
32700 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61   .** second para
32710 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69  meter.  ^The thi
32720 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
32730 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
32740 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
32750 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
32760 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
32770 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a  .   ^The fourth.
32780 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
32790 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69  an arbitrary cli
327a0 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ent data pointer
327b0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
327c0 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20  through.** into 
327d0 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
327e0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
327f0 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74  hods of the virt
32800 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
32810 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76  .** when a new v
32820 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
32830 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  be being created
32840 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65   or reinitialize
32850 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
32860 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
32870 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ule_v2() interfa
32880 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70  ce has a fifth p
32890 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
328a0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
328b0 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
328c0 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  or the pClientDa
328d0 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ta.  ^SQLite wil
328e0 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  l.** invoke the 
328f0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
32900 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f  ion (if it is no
32910 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c  t NULL) when SQL
32920 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72  ite.** no longer
32930 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65   needs the pClie
32940 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  ntData pointer. 
32950 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
32960 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a  eate_module().**
32970 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
32980 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69  uivalent to sqli
32990 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
329a0 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
329b0 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  LL.** destructor
329c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
329d0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
329e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
329f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32a00 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
32a10 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
32a20 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
32a30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
32a40 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
32a50 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
32a60 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
32a70 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
32a80 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
32a90 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
32aa0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
32ab0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
32ac0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
32ad0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
32ae0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32af0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
32b00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32b10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32b20 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
32b30 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
32b40 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
32b50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
32b60 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
32b70 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
32b80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
32b90 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
32ba0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
32bb0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
32bc0 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
32bd0 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
32be0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
32bf0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
32c00 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
32c10 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
32c20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
32c30 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
32c40 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32c50 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
32c60 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
32c70 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
32c80 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a  sqlite3_vtab.**.
32c90 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
32ca0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
32cb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
32cc0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a  ses a subclass.*
32cd0 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  * of this object
32ce0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
32cf0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
32d00 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  ce.** of the [vi
32d10 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45  rtual table].  E
32d20 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c  ach subclass wil
32d30 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64  l.** be tailored
32d40 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
32d50 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f   needs of the mo
32d60 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
32d70 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70  ion..** The purp
32d80 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
32d90 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
32da0 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
32db0 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63  ds that are.** c
32dc0 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64  ommon to all mod
32dd0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
32de0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74  ons..**.** ^Virt
32df0 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f  ual tables metho
32e00 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72  ds can set an er
32e10 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61  ror message by a
32e20 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74  ssigning a.** st
32e30 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
32e40 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
32e50 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73  ntf()] to zErrMs
32e60 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
32e70 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
32e80 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
32e90 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
32ea0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
32eb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
32ec0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
32ed0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
32ee0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
32ef0 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72  ^After the error
32f00 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
32f10 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
32f20 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
32f30 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
32f40 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
32f50 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
32f60 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
32f70 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
32f80 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
32f90 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
32fa0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
32fb0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
32fc0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
32fd0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
32fe0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
32ff0 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
33000 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
33010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
33020 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20   NO LONGER USED 
33030 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
33040 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
33050 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
33060 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
33070 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
33080 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
33090 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
330a0 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
330b0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
330c0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
330d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
330e0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
330f0 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  sor Object.** KE
33100 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
33110 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72  vtab_cursor {vir
33120 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
33130 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  r}.**.** Every [
33140 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33150 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
33160 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
33170 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  lass of the.** f
33180 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
33190 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  re to describe c
331a0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
331b0 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76  t into the.** [v
331c0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e  irtual table] an
331d0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
331e0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
331f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
33200 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
33210 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
33220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ** [sqlite3_modu
33230 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e  le.xOpen | xOpen
33240 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
33250 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64  module and are d
33260 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74  estroyed.** by t
33270 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  he [sqlite3_modu
33280 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f  le.xClose | xClo
33290 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72  se] method.  Cur
332a0 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a  sors are used.**
332b0 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72   by the [xFilter
332c0 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f  ], [xNext], [xEo
332d0 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61  f], [xColumn], a
332e0 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68  nd [xRowid] meth
332f0 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f  ods.** of the mo
33300 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75  dule.  Each modu
33310 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
33320 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a  n will define.**
33330 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
33340 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75  a cursor structu
33350 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f  re to suit its o
33360 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  wn needs..**.** 
33370 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  This superclass 
33380 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20  exists in order 
33390 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73  to define fields
333a0 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74   of the cursor t
333b0 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f  hat.** are commo
333c0 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  n to all impleme
333d0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72  ntations..*/.str
333e0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
333f0 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69  _cursor {.  sqli
33400 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b  te3_vtab *pVtab;
33410 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c        /* Virtual
33420 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63   table of this c
33430 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69  ursor */.  /* Vi
33440 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
33450 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
33460 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
33470 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
33480 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
33490 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20  PI3REF: Declare 
334a0 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20  The Schema Of A 
334b0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
334c0 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74  .** ^The [xCreat
334d0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
334e0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
334f0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
33500 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
33510 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
33520 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
33530 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
33540 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
33550 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
33560 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
33570 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
33580 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lement..*/.int s
33590 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
335a0 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
335b0 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
335c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
335d0 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
335e0 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
335f0 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
33600 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  ^(Virtual tables
33610 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
33620 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
33630 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
33640 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
33650 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
33660 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
33670 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
33680 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
33690 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
336a0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
336b0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
336c0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
336d0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a  e overloaded.)^.
336e0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49  **.** ^(This API
336f0 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
33700 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
33710 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
33720 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
33730 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
33740 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
33750 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
33760 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
33770 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
33780 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
33790 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
337a0 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54  s created.)^  ^T
337b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
337c0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
337d0 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
337e0 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
337f0 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
33800 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
33810 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
33820 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
33830 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
33840 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
33850 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
33860 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  aceholder functi
33870 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
33880 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
33890 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
338a0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
338b0 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
338c0 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
338d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
338e0 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
338f0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
33900 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
33910 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
33920 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
33930 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
33940 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
33950 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
33960 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
33970 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
33980 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
33990 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
339a0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
339b0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
339c0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
339d0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
339e0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
339f0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
33a00 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
33a10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
33a20 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
33a30 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
33a40 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
33a50 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
33a60 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
33a70 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
33a80 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
33a90 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
33aa0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
33ab0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
33ac0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
33ad0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42   KEYWORDS: {BLOB
33ae0 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68   handle} {BLOB h
33af0 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  andles}.**.** An
33b00 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
33b10 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
33b20 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42  nts an open BLOB
33b30 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71   on which.** [sq
33b40 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
33b50 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
33b60 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70  OB I/O] can be p
33b70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62  erformed..** ^Ob
33b80 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
33b90 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
33ba0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
33bb0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64  open()].** and d
33bc0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
33bd0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33be0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  )]..** ^The [sql
33bf0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
33c00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
33c10 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74  lob_write()] int
33c20 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62  erfaces.** can b
33c30 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f  e used to read o
33c40 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75  r write small su
33c50 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  bsections of the
33c60 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b   BLOB..** ^The [
33c70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
33c80 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
33c90 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
33ca0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20   of the BLOB in 
33cb0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  bytes..*/.typede
33cc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33cd0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c  _blob sqlite3_bl
33ce0 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ob;../*.** CAPI3
33cf0 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42  REF: Open A BLOB
33d00 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c   For Incremental
33d10 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69   I/O.**.** ^(Thi
33d20 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65  s interfaces ope
33d30 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ns a [BLOB handl
33d40 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74  e | handle] to t
33d50 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a  he BLOB located.
33d60 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20  ** in row iRow, 
33d70 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
33d80 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
33d90 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a  database zDb;.**
33da0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
33db0 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74   the same BLOB t
33dc0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c  hat would be sel
33dd0 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
33de0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
33df0 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
33e00 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
33e10 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77  E [rowid] = iRow
33e20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  ;.** </pre>)^.**
33e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67  .** ^If the flag
33e40 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
33e50 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
33e60 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
33e70 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64   for read.** and
33e80 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e   write access. ^
33e90 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
33ea0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
33eb0 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73  d for read acces
33ec0 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74  s..** ^It is not
33ed0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65   possible to ope
33ee0 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  n a column that 
33ef0 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e  is part of an in
33f00 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a  dex or primary .
33f10 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69  ** key for writi
33f20 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e  ng. ^If [foreign
33f30 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
33f40 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69  ] are enabled, i
33f50 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73  t is .** not pos
33f60 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
33f70 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
33f80 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20  art of a [child 
33f90 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67  key] for writing
33fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
33fb0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
33fc0 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20  name is not the 
33fd0 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f  filename that co
33fe0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61  ntains.** the da
33ff0 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65  tabase but rathe
34000 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  r the symbolic n
34010 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
34020 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65  ase that.** appe
34030 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53  ars after the AS
34040 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68   keyword when th
34050 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f  e database is co
34060 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41  nnected using [A
34070 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20  TTACH]..** ^For 
34080 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
34090 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  e file, the data
340a0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61  base name is "ma
340b0 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d  in"..** ^For TEM
340c0 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61  P tables, the da
340d0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
340e0 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  temp"..**.** ^(O
340f0 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
34100 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
34110 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b  ed and the new [
34120 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20  BLOB handle] is 
34130 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
34140 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65  pBlob. Otherwise
34150 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
34160 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
34170 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a   *ppBlob is set.
34180 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20  ** to be a null 
34190 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54  pointer.)^.** ^T
341a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
341b0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
341c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f  connection] erro
341d0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
341e0 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
341f0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
34200 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
34210 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
34220 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66  and related.** f
34230 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20  unctions. ^Note 
34240 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62  that the *ppBlob
34250 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77   variable is alw
34260 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  ays initialized 
34270 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74  in a.** way that
34280 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74   makes it safe t
34290 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  o invoke [sqlite
342a0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20  3_blob_close()] 
342b0 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65  on *ppBlob.** re
342c0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
342d0 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
342e0 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  re of this routi
342f0 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ne..**.** ^(If t
34300 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c  he row that a BL
34310 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73  OB handle points
34320 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20   to is modified 
34330 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45  by an.** [UPDATE
34340 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20  ], [DELETE], or 
34350 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  by [ON CONFLICT]
34360 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a   side-effects.**
34370 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68   then the BLOB h
34380 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20  andle is marked 
34390 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a  as "expired"..**
343a0 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66   This is true if
343b0 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   any column of t
343c0 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65  he row is change
343d0 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e  d, even a column
343e0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74  .** other than t
343f0 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20  he one the BLOB 
34400 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f  handle is open o
34410 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  n.)^.** ^Calls t
34420 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
34430 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
34440 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
34450 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69  )] for.** a expi
34460 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  red BLOB handle 
34470 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74  fail with an ret
34480 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
34490 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e  ITE_ABORT]..** ^
344a0 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e  (Changes written
344b0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69   into a BLOB pri
344c0 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65  or to the BLOB e
344d0 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a  xpiring are not.
344e0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
344f0 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e  y the expiration
34500 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53   of the BLOB.  S
34510 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  uch changes will
34520 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63   eventually.** c
34530 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61  ommit if the tra
34540 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75  nsaction continu
34550 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
34560 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74  .)^.**.** ^Use t
34570 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
34580 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
34590 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
345a0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
345b0 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
345c0 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61    ^The size of a
345d0 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
345e0 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
345f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
34600 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
34610 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
34620 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
34630 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
34640 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
34650 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
34660 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34670 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
34680 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
34690 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
346a0 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
346b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
346c0 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
346d0 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
346e0 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
346f0 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
34700 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
34710 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
34720 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
34730 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
34740 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
34750 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
34760 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
34770 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
34780 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
34790 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
347a0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a  ob_close()]..*/.
347b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
347c0 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
347d0 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
347e0 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
347f0 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
34800 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
34810 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
34820 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
34830 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
34840 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
34850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34860 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
34870 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  andle.**.** ^Clo
34880 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  ses an open [BLO
34890 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  B handle]..**.**
348a0 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42   ^Closing a BLOB
348b0 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
348c0 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
348d0 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
348e0 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
348f0 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
34900 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
34910 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
34920 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
34930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34940 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
34950 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e  mode]..** ^If an
34960 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
34970 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
34980 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
34990 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
349a0 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
349b0 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
349c0 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
349d0 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42   ^(Closing the B
349e0 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
349f0 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
34a00 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
34a10 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
34a20 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
34a30 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
34a40 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
34a50 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
34a60 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20  is closed.  Any 
34a70 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
34a80 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
34a90 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
34aa0 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
34ab0 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a  eturn value.)^.*
34ac0 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20  *.** ^(The BLOB 
34ad0 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64  is closed uncond
34ae0 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e  itionally.  Even
34af0 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   if this routine
34b00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65   returns.** an e
34b10 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42  rror code, the B
34b20 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f  LOB is still clo
34b30 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  sed.)^.**.** ^Ca
34b40 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
34b50 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70  ne with a null p
34b60 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20  ointer (such as 
34b70 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  would be returne
34b80 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64  d.** by a failed
34b90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34ba0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
34bb0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
34bc0 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
34bd0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
34be0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
34bf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34c00 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
34c10 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
34c20 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20  .**.** ^Returns 
34c30 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
34c40 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
34c50 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
34c60 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c   .** successfull
34c70 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68  y opened [BLOB h
34c80 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
34c90 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  ly argument.  ^T
34ca0 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  he.** incrementa
34cb0 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69  l blob I/O routi
34cc0 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61  nes can only rea
34cd0 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67  d or overwriting
34ce0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f   existing.** blo
34cf0 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20  b content; they 
34d00 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
34d10 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
34d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34d30 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
34d40 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
34d50 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
34d60 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
34d70 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
34d80 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
34d90 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34da0 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
34db0 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
34dc0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
34dd0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
34de0 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
34df0 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
34e00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34e10 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34e20 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
34e30 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
34e40 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  vior..*/.int sql
34e50 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34e60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
34e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34e80 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d  : Read Data From
34e90 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
34ea0 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tally.**.** ^(Th
34eb0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
34ec0 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
34ed0 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42   from an open [B
34ee0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  LOB handle] into
34ef0 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
34f00 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
34f10 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34f20 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
34f30 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74  ffer Z.** from t
34f40 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74  he open BLOB, st
34f50 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
34f60 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a   iOffset.)^.**.*
34f70 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66  * ^If offset iOf
34f80 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
34f90 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
34fa0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
34fb0 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
34fc0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
34fd0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
34fe0 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72   read.  ^If N or
34ff0 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
35000 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
35010 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
35020 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
35030 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
35040 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74  * ^The size of t
35050 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e  he blob (and hen
35060 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
35070 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
35080 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
35090 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
350a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
350b0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
350c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
350d0 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72  tempt to read fr
350e0 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  om an expired [B
350f0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
35100 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
35110 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
35120 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
35130 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73   ^(On success, s
35140 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
35150 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
35160 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
35170 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
35180 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
35190 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
351a0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
351b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
351c0 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
351d0 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
351e0 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
351f0 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
35200 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
35210 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35220 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
35230 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
35240 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
35250 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
35260 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
35270 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
35280 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
35290 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
352a0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
352b0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
352c0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
352d0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
352e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
352f0 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  _write()]..*/.in
35300 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
35310 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
35320 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
35330 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
35340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35350 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
35360 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
35370 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  entally.**.** ^T
35380 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
35390 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
353a0 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
353b0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
353c0 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
353d0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
353e0 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61  ^N bytes of data
353f0 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
35400 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
35410 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
35420 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
35430 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
35440 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
35450 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73  BLOB handle] pas
35460 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
35470 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f   argument was no
35480 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20  t opened for.** 
35490 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61  writing (the fla
354a0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
354b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
354c0 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c  en()] was zero),
354d0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
354e0 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
354f0 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
35500 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
35510 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66  n may only modif
35520 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  y the contents o
35530 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69  f the BLOB; it i
35540 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
35550 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68  e to increase th
35560 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  e size of a BLOB
35570 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e   using this API.
35580 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
35590 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
355a0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
355b0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
355c0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
355d0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
355e0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
355f0 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66  is written.  ^If
35600 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
35610 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
35620 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
35630 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
35640 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68  s written..** Th
35650 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
35660 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  OB (and hence th
35670 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
35680 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
35690 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
356a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
356b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
356c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
356d0 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
356e0 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20   to write to an 
356f0 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
35700 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
35710 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
35720 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
35730 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f  RT].  ^Writes to
35740 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f   the BLOB that o
35750 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72  ccurred.** befor
35760 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  e the [BLOB hand
35770 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20  le] expired are 
35780 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  not rolled back 
35790 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61  by the.** expira
357a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64  tion of the hand
357b0 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  le, though of co
357c0 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67  urse those chang
357d0 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65  es might.** have
357e0 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65   been overwritte
357f0 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  n by the stateme
35800 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20  nt that expired 
35810 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a  the BLOB handle.
35820 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69  ** or by other i
35830 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65  ndependent state
35840 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  ments..**.** ^(O
35850 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74  n success, sqlit
35860 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20  e3_blob_write() 
35870 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
35880 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
35890 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65   an  [error code
358a0 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
358b0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
358c0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
358d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
358e0 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
358f0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
35900 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
35910 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
35920 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
35930 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
35940 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
35950 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
35960 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
35970 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
35980 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
35990 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
359a0 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
359b0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
359c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
359d0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
359e0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
359f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
35a00 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
35a10 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ead()]..*/.int s
35a20 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
35a30 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
35a40 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c  , const void *z,
35a50 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
35a60 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
35a70 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46  I3REF: Virtual F
35a80 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
35a90 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  ts.**.** A virtu
35aa0 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
35ab0 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
35ac0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
35ad0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
35ae0 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
35af0 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
35b00 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
35b10 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
35b20 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
35b30 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
35b40 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
35b50 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
35b60 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
35b70 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
35b80 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
35b90 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
35ba0 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
35bb0 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
35bc0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
35bd0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
35be0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
35bf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73  ^The sqlite3_vfs
35c00 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
35c10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35c20 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
35c30 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
35c40 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20  ^Names are case 
35c50 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e  sensitive..** ^N
35c60 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65  ames are zero-te
35c70 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
35c80 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74  trings..** ^If t
35c90 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
35ca0 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  , a NULL pointer
35cb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35cc0 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73   ^If zVfsName is
35cd0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
35ce0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
35cf0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  turned..**.** ^N
35d00 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
35d10 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
35d20 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
35d30 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65  r()..** ^Each ne
35d40 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
35d50 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
35d60 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
35d70 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54  ag is set..** ^T
35d80 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20  he same VFS can 
35d90 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
35da0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
35db0 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20  hout injury..** 
35dc0 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73  ^To make an exis
35dd0 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
35de0 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
35df0 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
35e00 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
35e10 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
35e20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e   If two differen
35e30 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65  t VFSes with the
35e40 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  .** same name ar
35e50 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68  e registered, th
35e60 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
35e70 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a  defined.  If a.*
35e80 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65  * VFS is registe
35e90 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20  red with a name 
35ea0 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20  that is NULL or 
35eb0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
35ec0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
35ed0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
35ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67  ed..**.** ^Unreg
35ef0 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
35f00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
35f10 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
35f20 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66  terface..** ^(If
35f30 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
35f40 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64   is unregistered
35f50 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73  , another VFS is
35f60 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68   chosen as.** th
35f70 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20  e default.  The 
35f80 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e  choice for the n
35f90 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72  ew VFS is arbitr
35fa0 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65  ary.)^.*/.sqlite
35fb0 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
35fc0 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
35fd0 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
35fe0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
35ff0 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
36000 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
36010 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
36020 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
36030 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
36040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36050 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Mutexes.**.** Th
36060 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
36070 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
36080 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20  s for thread.** 
36090 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e  synchronization.
360a0 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65   Though they are
360b0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e   intended for in
360c0 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
360d0 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68   SQLite, code th
360e0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
360f0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65   SQLite is.** pe
36100 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61  rmitted to use a
36110 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
36120 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
36130 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
36140 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74  de contains mult
36150 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
36160 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ions.** of these
36170 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
36180 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
36190 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
361a0 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
361b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
361c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e  compile-time.  ^
361d0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  (The following.*
361e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
361f0 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
36200 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
36210 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
36220 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
36230 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
36240 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
36250 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
36260 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
36270 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
36280 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
36290 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
362a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54   ^The SQLITE_MUT
362b0 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e  EX_NOOP implemen
362c0 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20  tation is a set 
362d0 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74  of routines.** t
362e0 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
362f0 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
36300 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
36310 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67  use in.** a sing
36320 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  le-threaded appl
36330 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53  ication.  ^The S
36340 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
36350 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
36360 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
36370 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
36380 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
36390 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
363a0 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
363b0 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
363c0 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  dows..**.** ^(If
363d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
363e0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
363f0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
36400 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
36410 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
36420 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
36430 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
36440 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
36450 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
36460 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
36470 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49  h the library. I
36480 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a  n this case the.
36490 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  ** application m
364a0 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73  ust supply a cus
364b0 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  tom mutex implem
364c0 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74  entation using t
364d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
364e0 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
364f0 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  on of the sqlite
36500 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74  3_config() funct
36510 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61  ion.** before ca
36520 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e  lling sqlite3_in
36530 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e  itialize() or an
36540 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73  y other public s
36550 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74  qlite3_.** funct
36560 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73  ion that calls s
36570 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
36580 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  e().)^.**.** ^Th
36590 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
365a0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
365b0 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
365c0 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
365d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
365e0 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74  o it. ^If it ret
365f0 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61  urns NULL.** tha
36600 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d  t means that a m
36610 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62  utex could not b
36620 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53  e allocated.  ^S
36630 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
36640 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
36650 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
36660 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  or.  ^(The argum
36670 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
36680 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
36690 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
366a0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
366b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
366c0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
366d0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
366e0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
366f0 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
36700 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
36710 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
36720 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36730 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
36740 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36750 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
36760 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
36770 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
36780 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
36790 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
367a0 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  RU.** <li>  SQLI
367b0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
367c0 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  LRU2.** </ul>)^.
367d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
367e0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28   two constants (
367f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
36800 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  T and SQLITE_MUT
36810 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a  EX_RECURSIVE).**
36820 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
36830 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
36840 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
36850 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77  mutex.  ^The new
36860 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
36870 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
36880 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
36890 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
368a0 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
368b0 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
368c0 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
368d0 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
368e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
368f0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
36900 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
36910 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
36920 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36930 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
36940 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
36950 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
36960 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69   to.  ^SQLite wi
36970 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20  ll only request 
36980 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  a recursive mute
36990 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68  x in.** cases wh
369a0 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65  ere it really ne
369b0 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20  eds one.  ^If a 
369c0 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
369d0 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
369e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
369f0 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
36a00 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
36a10 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
36a20 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
36a30 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
36a40 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
36a50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
36a60 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74  T..**.** ^The ot
36a70 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61  her allowed para
36a80 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65  meters to sqlite
36a90 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
36aa0 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a  (anything other.
36ab0 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  ** than SQLITE_M
36ac0 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51  UTEX_FAST and SQ
36ad0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
36ae0 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72  SIVE) each retur
36af0 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
36b00 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
36b10 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e  isting mutex.  ^
36b20 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78  Six static mutex
36b30 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62  es are.** used b
36b40 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65  y the current ve
36b50 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e  rsion of SQLite.
36b60 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
36b70 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
36b80 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ay add additiona
36b90 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  l static mutexes
36ba0 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65  .  Static mutexe
36bb0 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e  s are for intern
36bc0 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
36bd0 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ite only.  Appli
36be0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
36bf0 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20   SQLite mutexes 
36c00 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e  should.** use on
36c10 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  ly the dynamic m
36c20 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20  utexes returned 
36c30 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  by SQLITE_MUTEX_
36c40 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54  FAST or.** SQLIT
36c50 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36c60 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  E..**.** ^Note t
36c70 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
36c80 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
36c90 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
36ca0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
36cb0 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
36cc0 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
36cd0 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
36ce0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
36cf0 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
36d00 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
36d10 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74  very call.  ^But
36d20 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a   for the static.
36d30 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
36d40 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
36d50 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
36d60 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
36d70 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
36d80 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
36d90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
36da0 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
36db0 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
36dc0 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
36dd0 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
36de0 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65   mutex.  ^SQLite
36df0 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
36e00 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
36e10 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
36e20 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
36e30 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
36e40 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
36e50 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77  t be in.** use w
36e60 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
36e70 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d  llocated.  Attem
36e80 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
36e90 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
36ea0 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
36eb0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
36ec0 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65  ior.  ^SQLite ne
36ed0 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
36ee0 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
36ef0 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  x..**.** ^The sq
36f00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
36f10 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
36f20 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
36f30 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
36f40 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
36f50 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74  .  ^If another t
36f60 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
36f70 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65   within the mute
36f80 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  x,.** sqlite3_mu
36f90 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c  tex_enter() will
36fa0 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74   block and sqlit
36fb0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77  e3_mutex_try() w
36fc0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  ill return.** SQ
36fd0 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65  LITE_BUSY.  ^The
36fe0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
36ff0 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
37000 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
37010 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  K].** upon succe
37020 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28  ssful entry.  ^(
37030 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20  Mutexes created 
37040 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
37050 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
37060 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d  can be entered m
37070 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79  ultiple times by
37080 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
37090 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73  ..** In such cas
370a0 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
370b0 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
370c0 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
370d0 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
370e0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
370f0 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20  * can enter.)^  
37100 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68  ^(If the same th
37110 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e  read tries to en
37120 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  ter any other.**
37130 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d   kind of mutex m
37140 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74  ore than once, t
37150 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
37160 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c  ndefined..** SQL
37170 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
37180 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
37190 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
371a0 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
371b0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d  s.)^.**.** ^(Som
371c0 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
371d0 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
371e0 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
371f0 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
37200 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
37210 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
37220 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
37230 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
37240 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
37250 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
37260 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
37270 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
37280 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65  re only ever use
37290 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  s.** sqlite3_mut
372a0 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f  ex_try() as an o
372b0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74  ptimization so t
372c0 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c  his is acceptabl
372d0 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a  e behavior.)^.**
372e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
372f0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72  _mutex_leave() r
37300 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d  outine exits a m
37310 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a  utex that was.**
37320 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65   previously ente
37330 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20  red by the same 
37340 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20  thread.   ^(The 
37350 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
37360 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
37370 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
37380 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
37390 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
373a0 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
373b0 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
373c0 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77  cated.  SQLite w
373d0 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20  ill.** never do 
373e0 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  either.)^.**.** 
373f0 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
37400 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
37410 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
37420 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
37430 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
37440 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
37450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
37460 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
37470 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
37480 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
37490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
374a0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
374b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
374c0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
374d0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
374e0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
374f0 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
37500 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
37510 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
37520 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
37530 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
37540 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
37550 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
37560 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
37570 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
37580 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
37590 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
375a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
375b0 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
375c0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
375d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
375e0 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69  s structure defi
375f0 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65  nes the low-leve
37600 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  l routines.** us
37610 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  ed to allocate a
37620 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a  nd use mutexes..
37630 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74  **.** Usually, t
37640 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
37650 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37660 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c   provided by SQL
37670 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69  ite are.** suffi
37680 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74  cient, however t
37690 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20  he user has the 
376a0 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69  option of substi
376b0 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a  tuting a custom.
376c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
376d0 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65  n for specialize
376e0 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72  d deployments or
376f0 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69   systems for whi
37700 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65  ch SQLite.** doe
37710 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  s not provide a 
37720 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
37730 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  ntation. In this
37740 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a   case, the user.
37750 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70  ** creates and p
37760 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74  opulates an inst
37770 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
37780 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a  ucture to pass.*
37790 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  * to sqlite3_con
377a0 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68  fig() along with
377b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
377c0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
377d0 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  n..** Additional
377e0 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ly, an instance 
377f0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37800 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  e can be used as
37810 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61   an.** output va
37820 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72  riable when quer
37830 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20  ying the system 
37840 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
37850 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
37860 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74  ntation, using t
37870 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
37880 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69  G_GETMUTEX] opti
37890 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  on..**.** ^The x
378a0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
378b0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
378c0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e   structure is in
378d0 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  voked as.** part
378e0 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69   of system initi
378f0 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65  alization by the
37900 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
37910 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a  ize() function..
37920 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e  ** ^The xMutexIn
37930 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  it routine is ca
37940 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78  lle by SQLite ex
37950 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65  actly once for e
37960 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65  ach.** effective
37970 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37980 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e  3_initialize()].
37990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
379a0 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66  exEnd method def
379b0 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
379c0 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
379d0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
379e0 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20  system shutdown 
379f0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
37a00 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69  hutdown() functi
37a10 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65  on. The.** imple
37a20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
37a30 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65  s method is expe
37a40 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  cted to release 
37a50 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a  all outstanding.
37a60 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74  ** resources obt
37a70 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74  ained by the mut
37a80 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65  ex methods imple
37a90 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63  mentation, espec
37aa0 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f  ially.** those o
37ab0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78  btained by the x
37ac0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
37ad0 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e  .  ^The xMutexEn
37ae0 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
37af0 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   is invoked exac
37b00 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  tly once for eac
37b10 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
37b20 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
37b30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61  **.** ^(The rema
37b40 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68  ining seven meth
37b50 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74  ods defined by t
37b60 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78  his structure (x
37b70 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78  MutexAlloc,.** x
37b80 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65  MutexFree, xMute
37b90 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72  xEnter, xMutexTr
37ba0 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20  y, xMutexLeave, 
37bb0 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a  xMutexHeld and.*
37bc0 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  * xMutexNotheld)
37bd0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66   implement the f
37be0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
37bf0 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c  ces (respectivel
37c00 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y):.**.** <ul>.*
37c10 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37c20 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
37c30 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
37c40 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
37c50 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a  x_free()] </li>.
37c60 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
37c70 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
37c80 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
37c90 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37ca0 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a  ex_try()] </li>.
37cb0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
37cc0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
37cd0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
37ce0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37cf0 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  ex_held()] </li>
37d00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
37d10 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37d20 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  ld()] </li>.** <
37d30 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
37d40 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
37d50 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62   is that the pub
37d60 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20  lic sqlite3_XXX 
37d70 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72  functions enumer
37d80 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69  ated.** above si
37d90 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e  lently ignore an
37da0 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68  y invocations th
37db0 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70  at pass a NULL p
37dc0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a  ointer instead.*
37dd0 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  * of a valid mut
37de0 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69  ex handle. The i
37df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37e00 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65  f the methods de
37e10 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  fined.** by this
37e20 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e   structure are n
37e30 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68  ot required to h
37e40 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c  andle this case,
37e50 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20   the results.** 
37e60 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c  of passing a NUL
37e70 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
37e80 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  d of a valid mut
37e90 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e  ex handle are un
37ea0 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e  defined.** (i.e.
37eb0 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c   it is acceptabl
37ec0 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20  e to provide an 
37ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
37ee0 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66  hat segfaults if
37ef0 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64  .** it is passed
37f00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29   a NULL pointer)
37f10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
37f20 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20  exInit() method 
37f30 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
37f40 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65  fe.  ^It must be
37f50 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20   harmless to.** 
37f60 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69  invoke xMutexIni
37f70 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65  t() mutiple time
37f80 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
37f90 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69  e process and wi
37fa0 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65  thout.** interve
37fb0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d  ning calls to xM
37fc0 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f  utexEnd().  Seco
37fd0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
37fe0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d  t calls to.** xM
37ff0 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20  utexInit() must 
38000 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
38010 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d   ^xMutexInit() m
38020 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
38030 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te memory alloca
38040 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d  tion ([sqlite3_m
38050 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20  alloc()].** and 
38060 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e  its associates).
38070 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d    ^Similarly, xM
38080 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74  utexAlloc() must
38090 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
380a0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
380b0 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69  tion for a stati
380c0 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76  c mutex.  ^Howev
380d0 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  er xMutexAlloc()
380e0 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a   may use SQLite.
380f0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
38100 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20  tion for a fast 
38110 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  or recursive mut
38120 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ex..**.** ^SQLit
38130 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
38140 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65  e xMutexEnd() me
38150 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  thod when [sqlit
38160 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69  e3_shutdown()] i
38170 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74  s.** called, but
38180 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69   only if the pri
38190 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65  or call to xMute
381a0 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53  xInit returned S
381b0 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20  QLITE_OK..** If 
381c0 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73  xMutexInit fails
381d0 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20   in any way, it 
381e0 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63  is expected to c
381f0 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74  lean up after it
38200 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  self.** prior to
38210 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74   returning..*/.t
38220 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
38230 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
38240 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ods sqlite3_mute
38250 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  x_methods;.struc
38260 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
38270 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
38280 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f  (*xMutexInit)(vo
38290 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  id);.  int (*xMu
382a0 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20  texEnd)(void);. 
382b0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a   sqlite3_mutex *
382c0 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69  (*xMutexAlloc)(i
382d0 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d  nt);.  void (*xM
382e0 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65  utexFree)(sqlite
382f0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
38300 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72  id (*xMutexEnter
38310 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
38320 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
38330 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d  exTry)(sqlite3_m
38340 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
38350 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73  (*xMutexLeave)(s
38360 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
38370 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48  .  int (*xMutexH
38380 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  eld)(sqlite3_mut
38390 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
383a0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71  MutexNotheld)(sq
383b0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
383c0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
383d0 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69  EF: Mutex Verifi
383e0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
383f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
38400 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
38410 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
38420 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
38430 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
38440 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
38450 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
38460 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51  ements.  ^The SQ
38470 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
38480 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
38490 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
384a0 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
384b0 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
384c0 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
384d0 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
384e0 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
384f0 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f    ^The SQLite co
38500 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
38510 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
38520 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
38530 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
38540 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
38550 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
38560 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65  BUG flag.  ^Exte
38570 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65  rnal mutex imple
38580 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
38590 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20  e only required 
385a0 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65  to provide these
385b0 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c   routines if SQL
385c0 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20  ITE_DEBUG is.** 
385d0 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e  defined and if N
385e0 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66  DEBUG is not def
385f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
38600 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
38610 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
38620 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
38630 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
38640 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
38650 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
38660 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
38670 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
38680 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
38690 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75  tion is not requ
386a0 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64  ired to provided
386b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
386c0 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
386d0 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72  hat actually wor
386e0 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d  k. If the implem
386f0 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
38700 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e  t provide workin
38710 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  g.** versions of
38720 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
38730 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65   it should at le
38740 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62  ast provide stub
38750 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a  s that always.**
38760 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20   return true so 
38770 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f  that one does no
38780 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61  t get spurious a
38790 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65  ssertion failure
387a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
387b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
387c0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
387d0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
387e0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
387f0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
38800 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20  eturn 1.   This 
38810 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e  seems counter-in
38820 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a  tuitive since.**
38830 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74   clearly the mut
38840 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c  ex cannot be hel
38850 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
38860 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65   exist.  But the
38870 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74  .** the reason t
38880 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f  he mutex does no
38890 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75  t exist is becau
388a0 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20  se the build is 
388b0 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74  not.** using mut
388c0 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f  exes.  And we do
388d0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73   not want the as
388e0 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e  sert() containin
388f0