/ Hex Artifact Content
Login

Artifact 6f36690f4749cbfdd778054a4c79bf4016b794a3:


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 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90d0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
90e0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
90f0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9100: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
9110: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
9120: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
9130: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
9140: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
9150: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
9160: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
9170: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
9180: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
9190: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
91a0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
91b0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
91c0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
91d0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
91e0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
91f0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
9200: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
9210: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
9220: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
9230: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
9240: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
9250: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
9260: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9270: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
9280: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
9290: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
92a0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
92b0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
92c0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
92d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
92e0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
92f0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
9300: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
9310: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9320: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
9330: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
9340: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
9350: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
9360: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9370: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
9380: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
9390: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
93a0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
93b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
93c0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
93d0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
93e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
93f0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
9400: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
9410: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
9420: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
9430: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
9440: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
9450: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
9460: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
9470: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
9480: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
9490: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
94a0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
94b0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
94d0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
94e0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
94f0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
9500: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
9510: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
9520: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
9530: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
9540: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
9550: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
9560: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
9570: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
9580: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
9590: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
95a0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
95b0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
95c0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
95d0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
95e0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
95f0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9600: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
9610: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
9620: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9630: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9640: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
9650: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
9660: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
9670: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
9680: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
9690: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
96a0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
96b0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
96c0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
96d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
96e0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
96f0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9700: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
9710: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9720: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
9730: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9740: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9750: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
9760: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9770: 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20  itable..** With 
9780: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9790: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
97a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
97b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
97c0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a  e is readable..*
97d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
97e0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
97f0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
9800: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
9810: 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ITE 1.#define SQ
9820: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9830: 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43        2../*.** C
9840: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
9850: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
9860: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
9870: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9880: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9890: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
98a0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
98b0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
98c0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
98d0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
98e0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
98f0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
9900: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
9910: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
9920: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
9930: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
9940: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
9950: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
9960: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
9970: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
9980: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
9990: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
99a0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
99b0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
99c0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
99d0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
99e0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
99f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
9a00: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
9a10: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
9a20: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
9a30: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
9a40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9a50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
9a60: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
9a70: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
9a80: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
9a90: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
9aa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9ab0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
9ac0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
9ad0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
9ae0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
9af0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
9b00: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
9b10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
9b20: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
9b30: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
9b40: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
9b50: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
9b60: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
9b70: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9b80: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
9b90: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
9ba0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
9bb0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
9bc0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
9bd0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
9be0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9bf0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
9c00: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
9c10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9c20: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
9c30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
9c40: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
9c50: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
9c60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
9c70: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
9c80: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
9c90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9ca0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
9cb0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
9cc0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9cd0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
9ce0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
9cf0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
9d00: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
9d10: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
9d20: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
9d30: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
9d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
9d50: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
9d60: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
9d70: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
9d80: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
9d90: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
9da0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
9db0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
9dc0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
9dd0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
9de0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
9df0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
9e00: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
9e10: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
9e20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9e30: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
9e40: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
9e50: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
9e60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9e70: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9e80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
9e90: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
9ea0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
9eb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9ec0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
9ed0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
9ee0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
9ef0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
9f00: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
9f10: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
9f20: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
9f30: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
9f40: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
9f50: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
9f60: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
9f70: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9f80: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9f90: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
9fa0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
9fb0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
9fc0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
9fd0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
9fe0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
9ff0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
a000: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a010: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
a020: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
a030: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
a040: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
a050: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
a060: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a070: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
a080: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
a090: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
a0a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
a0b0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
a0c0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
a0d0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
a0e0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
a0f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a100: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
a110: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
a120: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
a130: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
a140: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
a150: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
a160: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
a170: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
a180: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
a190: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
a1a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
a1b0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
a1c0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a1d0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a1e0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
a1f0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
a200: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
a210: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
a220: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
a230: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
a240: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
a250: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
a260: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
a270: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
a280: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
a290: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
a2a0: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
a2b0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
a2c0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
a2d0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
a2e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a2f0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
a300: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
a310: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
a320: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
a330: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
a340: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
a350: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
a360: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a370: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
a380: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
a390: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
a3a0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
a3b0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
a3c0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
a3d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
a3e0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
a3f0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
a400: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
a410: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
a420: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
a430: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
a440: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
a450: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
a460: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
a470: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
a480: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
a490: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
a4a0: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
a4b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
a4c0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
a4d0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
a4e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
a4f0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
a500: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
a510: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
a520: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
a530: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
a540: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
a550: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
a560: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
a570: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
a580: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
a590: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
a5a0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
a5b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a5c0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
a5d0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
a5e0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
a5f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
a600: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a610: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
a620: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
a630: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
a640: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
a650: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
a660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
a670: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
a680: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
a690: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
a6a0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
a6b0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
a6c0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
a6d0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
a6e0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
a6f0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
a700: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
a710: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
a720: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a730: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a740: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a750: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a760: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a770: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a780: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a790: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a7a0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a7b0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a7c0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a7d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a7e0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a7f0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a800: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a810: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a820: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a830: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a840: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a850: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a860: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a870: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a880: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a890: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a8a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a8b0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a8c0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a8d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a8e0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a8f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
a900: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a910: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a920: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a930: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
a940: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a950: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
a960: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
a970: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
a980: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
a990: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a9a0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
a9b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
a9c0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
a9d0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
a9e0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
a9f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
aa00: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
aa10: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
aa20: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
aa30: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
aa40: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
aa50: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
aa60: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
aa70: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
aa80: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
aa90: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
aaa0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
aab0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
aac0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
aad0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
aae0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
aaf0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
ab00: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
ab10: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
ab20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ab30: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
ab40: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
ab50: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
ab60: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
ab70: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ab80: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
ab90: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
aba0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
abb0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
abc0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
abd0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
abe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
abf0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
ac00: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ac10: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
ac20: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
ac30: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
ac40: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
ac50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ac60: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
ac70: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
ac80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ac90: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
aca0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
acb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
acc0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
acd0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
ace0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
acf0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
ad00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ad10: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
ad20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
ad30: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
ad40: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
ad50: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
ad60: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
ad70: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
ad80: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
ad90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ada0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
adb0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
adc0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
add0: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
ade0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
adf0: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
ae00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ae10: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
ae20: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
ae30: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
ae40: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
ae50: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
ae60: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
ae70: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ae80: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
ae90: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
aea0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
aeb0: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
aec0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
aed0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
aee0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
aef0: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
af00: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
af10: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
af20: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
af30: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
af40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
af50: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
af60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
af70: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
af80: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
af90: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
afa0: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
afb0: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
afc0: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
afd0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
afe0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
aff0: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
b000: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
b010: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
b020: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
b030: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
b040: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
b050: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
b060: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
b070: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
b080: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
b090: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
b0a0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
b0b0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
b0c0: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
b0d0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
b0e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
b0f0: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
b100: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
b110: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
b120: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
b130: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
b140: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
b150: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
b160: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
b170: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
b180: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
b190: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
b1a0: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
b1b0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
b1c0: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
b1d0: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
b1e0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
b1f0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
b200: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
b210: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
b220: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
b230: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
b240: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
b250: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
b260: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
b270: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
b280: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
b290: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
b2a0: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
b2b0: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
b2c0: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
b2d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
b2e0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
b2f0: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
b300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b310: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
b320: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b330: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
b340: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
b350: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b360: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
b370: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
b380: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
b390: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
b3a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3b0: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b3c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
b3d0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
b3e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
b3f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b400: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
b410: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b420: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
b430: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
b440: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
b450: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
b460: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
b470: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b480: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
b490: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
b4a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b4b0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b4c0: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
b4d0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
b4e0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b4f0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
b500: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
b510: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b520: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
b530: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
b540: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
b550: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
b560: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
b570: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
b580: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
b590: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
b5a0: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
b5b0: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
b5c0: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
b5d0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
b5e0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
b5f0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
b600: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
b610: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
b620: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
b630: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
b640: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
b650: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
b660: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
b670: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
b680: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
b690: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b6a0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
b6b0: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
b6c0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
b6d0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
b6e0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
b6f0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
b700: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
b710: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
b720: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
b730: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
b740: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
b750: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
b760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
b770: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
b780: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
b790: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
b7a0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
b7b0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
b7c0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
b7d0: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
b7e0: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
b7f0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
b800: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
b810: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
b820: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
b830: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
b840: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
b850: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
b860: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
b870: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
b880: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
b890: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
b8a0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
b8b0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
b8c0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
b8d0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
b8e0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
b8f0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
b900: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
b910: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
b920: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
b930: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
b940: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
b950: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
b960: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
b970: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
b980: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
b990: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
b9a0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
b9b0: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
b9c0: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
b9d0: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
b9e0: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
b9f0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
ba00: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
ba10: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
ba20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ba30: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
ba40: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
ba50: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
ba60: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
ba70: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
ba80: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
ba90: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
baa0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
bab0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
bac0: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
bad0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
bae0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
baf0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
bb00: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
bb10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
bb20: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
bb30: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
bb40: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
bb50: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
bb60: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
bb70: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
bb80: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
bb90: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
bba0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
bbb0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
bbc0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
bbd0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
bbe0: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
bbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
bc00: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
bc10: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
bc20: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
bc30: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
bc40: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
bc50: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
bc60: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
bc70: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
bc80: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
bc90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bca0: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
bcb0: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
bcc0: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
bcd0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bce0: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
bcf0: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
bd00: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
bd10: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
bd20: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
bd30: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
bd40: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
bd50: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
bd60: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
bd70: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
bd80: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
bd90: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
bda0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
bdb0: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
bdc0: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
bdd0: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
bde0: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
bdf0: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
be00: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
be10: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
be20: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
be30: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
be40: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
be50: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
be60: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
be70: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
be80: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
be90: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
bea0: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
beb0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
bec0: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
bed0: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
bee0: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
bef0: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
bf00: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
bf10: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
bf20: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
bf30: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
bf40: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
bf50: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
bf60: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
bf70: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
bf80: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
bf90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bfa0: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
bfb0: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
bfc0: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
bfd0: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
bfe0: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
bff0: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
c000: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
c010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c020: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
c030: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
c040: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
c050: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
c060: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
c070: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
c080: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
c090: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
c0a0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
c0b0: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
c0c0: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
c0d0: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
c0e0: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
c0f0: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
c100: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c110: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c120: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
c130: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
c140: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c150: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
c160: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
c170: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
c180: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
c190: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
c1a0: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
c1b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
c1c0: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
c1d0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
c1e0: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
c1f0: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
c200: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
c210: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
c220: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
c230: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
c240: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
c250: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c260: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
c270: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
c280: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
c290: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
c2a0: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
c2b0: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
c2c0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c2d0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
c2e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c2f0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
c300: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
c310: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
c320: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
c330: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
c340: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
c350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
c360: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
c370: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
c380: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
c390: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c3a0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
c3b0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
c3c0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
c3d0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
c3e0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
c3f0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
c400: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
c410: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
c420: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
c430: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
c440: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
c450: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
c460: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
c470: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
c480: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
c490: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
c4a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c4b0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
c4c0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
c4d0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
c4e0: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
c4f0: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
c500: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c510: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
c520: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
c530: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
c540: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c550: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
c560: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
c570: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
c580: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
c590: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
c5a0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
c5b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
c5c0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
c5d0: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
c5e0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c5f0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
c600: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
c610: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
c620: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
c630: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
c640: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
c650: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
c660: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
c670: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
c680: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
c690: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
c6a0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
c6b0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
c6c0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
c6d0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
c6e0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
c6f0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
c700: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
c710: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
c720: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
c730: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
c740: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
c750: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
c760: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
c770: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
c780: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
c790: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
c7a0: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
c7b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
c7c0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
c7d0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
c7e0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
c7f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c800: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
c810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c820: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
c830: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c840: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
c850: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c860: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c870: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c880: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
c890: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
c8a0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
c8b0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
c8c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
c8d0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
c8e0: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
c8f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c900: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
c910: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
c920: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c930: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
c940: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
c950: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
c960: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c970: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
c980: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
c990: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
c9a0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
c9b0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
c9c0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
c9d0: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
c9e0: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
c9f0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
ca00: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
ca10: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
ca20: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
ca30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ca40: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
ca50: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
ca60: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ca70: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ca80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ca90: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
caa0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
cab0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
cac0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
cad0: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
cae0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
caf0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
cb00: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
cb10: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
cb20: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
cb30: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
cb40: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
cb50: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
cb60: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
cb70: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
cb80: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
cb90: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
cba0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
cbb0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
cbc0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
cbd0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
cbe0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
cbf0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
cc00: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
cc10: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
cc20: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
cc30: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
cc40: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
cc50: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
cc60: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
cc70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
cc80: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
cc90: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
cca0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ccb0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ccc0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ccd0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
cce0: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
ccf0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
cd00: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
cd10: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
cd20: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
cd30: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
cd40: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
cd50: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
cd60: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
cd70: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
cd80: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
cd90: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
cda0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
cdb0: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
cdc0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
cdd0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
cde0: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
cdf0: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
ce00: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ce10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ce20: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ce30: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ce40: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ce50: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ce60: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
ce70: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
ce80: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
ce90: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
cea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
ceb0: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
cec0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
ced0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
cee0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
cef0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
cf00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
cf10: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
cf20: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cf30: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
cf40: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
cf50: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
cf60: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
cf70: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
cf80: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
cf90: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
cfa0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
cfb0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
cfc0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
cfd0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
cfe0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
cff0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d000: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
d010: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
d020: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
d030: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
d040: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
d050: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
d060: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
d070: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
d080: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
d090: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d0a0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d0b0: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
d0c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d0d0: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
d0e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d100: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
d110: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
d120: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
d130: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
d140: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
d150: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
d160: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
d170: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
d180: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
d190: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d1a0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
d1b0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
d1c0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
d1d0: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
d1e0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
d1f0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
d200: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
d210: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
d220: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d230: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
d240: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
d250: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
d260: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
d270: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
d280: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
d290: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
d2a0: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
d2b0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d2c0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
d2d0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
d2e0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
d2f0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
d300: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
d310: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
d320: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
d330: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
d340: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
d350: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
d360: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
d370: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
d380: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
d390: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d3a0: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
d3b0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
d3c0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
d3d0: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
d3e0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
d3f0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
d400: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
d410: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
d420: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
d430: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
d440: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
d450: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
d460: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
d470: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
d480: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
d490: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
d4a0: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
d4b0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
d4c0: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
d4d0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
d4e0: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
d4f0: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
d500: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
d510: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
d520: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
d530: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
d540: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
d550: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d560: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
d570: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
d580: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
d590: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
d5a0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
d5b0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
d5c0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
d5d0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
d5e0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
d5f0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
d600: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
d610: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
d620: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
d630: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
d640: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
d650: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
d660: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
d670: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
d680: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
d690: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
d6a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
d6b0: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
d6c0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d6d0: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
d6e0: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
d6f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
d700: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
d710: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
d720: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
d730: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69  equired due to i
d740: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64  nternal overhead
d750: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
d760: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
d770: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
d780: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
d790: 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
d7a0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
d7b0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
d7c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
d7d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
d7e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 70  scratch buffer p
d7f0: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
d800: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
d810: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65  t to the expecte
d820: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
d830: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53   of threads.  ^S
d840: 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
d850: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
d860: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
d870: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
d880: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
d890: 61 73 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65  ase.** page size
d8a0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
d8b0: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
d8c0: 6e 61 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  nal scratch memo
d8d0: 72 79 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68  ry beyond .** wh
d8e0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
d8f0: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
d900: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
d910: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
d920: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
d930: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
d940: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
d950: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
d960: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d970: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
d980: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
d990: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
d9a0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
d9b0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
d9c0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
d9d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
d9e0: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
d9f0: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
da00: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
da10: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
da20: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
da30: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
da40: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
da50: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
da60: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
da70: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
da80: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
da90: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
daa0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
dab0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
dac0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
dad0: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
dae0: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
daf0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
db00: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
db10: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
db20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
db30: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
db40: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
db50: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
db60: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
db70: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
db80: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
db90: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
dba0: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
dbb0: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
dbc0: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
dbd0: 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
dbe0: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
dbf0: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
dc00: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
dc10: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
dc20: 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
dc30: 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
dc40: 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
dc50: 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
dc60: 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
dc70: 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
dc80: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
dc90: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
dca0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
dcb0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
dcc0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
dcd0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
dce0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
dcf0: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
dd00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
dd10: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
dd20: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
dd30: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
dd40: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
dd50: 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
dd60: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
dd70: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
dd80: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
dd90: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
dda0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
ddb0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
ddc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
ddd0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
dde0: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
ddf0: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65  e space..** ^The
de00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
de10: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72  might use one or
de20: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62   more of the N b
de30: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a  uffers to hold .
de40: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  ** memory accoun
de50: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ting information
de60: 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  . The pointer in
de70: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
de80: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
de90: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
dea0: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
deb0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
dec0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
ded0: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
dee0: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
def0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
df00: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
df10: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
df20: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
df30: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
df40: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
df50: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
df60: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
df70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
df80: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
df90: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
dfa0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
dfb0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
dfc0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
dfd0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
dfe0: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
dff0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
e000: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
e010: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
e020: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
e030: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
e040: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
e050: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
e060: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
e070: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
e080: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
e090: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
e0a0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
e0b0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
e0c0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
e0d0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
e0e0: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
e0f0: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
e100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
e110: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
e120: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
e130: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e140: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
e150: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
e160: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
e170: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
e180: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
e190: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
e1a0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
e1b0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
e1c0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
e1d0: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
e1e0: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
e1f0: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
e200: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
e210: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
e220: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
e230: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
e240: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
e250: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
e260: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
e270: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
e280: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
e290: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
e2a0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
e2b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e2c0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
e2d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
e2e0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
e2f0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
e300: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
e310: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
e320: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
e330: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e340: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
e350: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
e360: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
e370: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
e380: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
e390: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
e3a0: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
e3b0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e3c0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
e3d0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
e3e0: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
e3f0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
e400: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
e410: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
e420: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
e430: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
e440: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
e450: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
e460: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
e470: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
e480: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
e490: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
e4a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e4b0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
e4c0: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
e4d0: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
e4e0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
e4f0: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
e500: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
e510: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
e520: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e530: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
e540: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
e550: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
e560: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
e570: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e580: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
e590: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
e5a0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
e5b0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
e5c0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
e5d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
e5e0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
e5f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
e600: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e610: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
e620: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e630: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
e640: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
e650: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
e660: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
e670: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
e680: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
e690: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
e6a0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
e6b0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
e6c0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
e6d0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
e6e0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
e6f0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
e700: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
e710: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
e720: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
e730: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e740: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e750: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
e760: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
e770: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
e780: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
e790: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
e7a0: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
e7b0: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
e7c0: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
e7d0: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
e7e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e7f0: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
e800: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
e810: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
e820: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
e830: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
e840: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
e850: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e860: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
e870: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
e880: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
e890: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
e8a0: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
e8b0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
e8c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
e8d0: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
e8e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e8f0: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
e900: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e910: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
e920: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
e930: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
e940: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
e950: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
e960: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
e970: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
e980: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
e990: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e9a0: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
e9b0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
e9c0: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
e9d0: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
e9e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
e9f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
ea00: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
ea10: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
ea20: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
ea30: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
ea40: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
ea50: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
ea60: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
ea70: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
ea80: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ea90: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
eaa0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
eab0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
eac0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ead0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
eae0: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
eaf0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
eb00: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
eb10: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
eb20: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
eb30: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
eb40: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
eb50: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
eb60: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
eb70: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
eb80: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
eb90: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
eba0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
ebb0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
ebc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
ebd0: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
ebe0: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ebf0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ec00: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ec10: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ec20: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
ec30: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
ec40: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
ec50: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
ec60: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
ec70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ec80: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
ec90: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
eca0: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
ecb0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ecc0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
ecd0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
ece0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ecf0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
ed00: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
ed10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ed20: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
ed30: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
ed40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ed50: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
ed60: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
ed70: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
ed80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ed90: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
eda0: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
edb0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
edc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
edd0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
ede0: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
edf0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
ee00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ee10: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
ee20: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
ee30: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
ee40: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
ee50: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
ee60: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
ee70: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
ee80: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
ee90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
eea0: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
eeb0: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
eec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eed0: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
eee0: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
eef0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ef00: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
ef10: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
ef20: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
ef30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ef40: 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
ef50: 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
ef60: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
ef70: 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
ef80: 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
ef90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
efa0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
efb0: 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
efc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
efd0: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
efe0: 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74      14  /* sqlit
eff0: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f000: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
f010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
f020: 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
f030: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f040: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f050: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f060: 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
f070: 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
f080: 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
f090: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
f0a0: 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
f0b0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
f0c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
f0d0: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
f0e0: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
f0f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f100: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
f110: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
f120: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f130: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
f140: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
f150: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
f160: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
f170: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
f180: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
f190: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
f1a0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
f1b0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
f1c0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
f1d0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
f1e0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
f1f0: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
f200: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
f210: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
f220: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
f230: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
f240: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
f250: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
f260: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
f270: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
f280: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
f290: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
f2a0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
f2b0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
f2c0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f2d0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
f2e0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
f2f0: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
f300: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f310: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
f320: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
f330: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
f340: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
f350: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
f360: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
f370: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
f380: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
f390: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f3a0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
f3b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
f3c0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
f3d0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
f3e0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
f3f0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
f400: 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  an memory buffer
f410: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
f420: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
f430: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
f440: 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
f450: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f460: 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
f470: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
f480: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
f490: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
f4a0: 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
f4b0: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
f4c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
f4d0: 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
f4e0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f4f0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
f500: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
f510: 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
f520: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
f530: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
f540: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
f550: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
f560: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
f570: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
f580: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
f590: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
f5a0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
f5b0: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
f5c0: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
f5d0: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
f5e0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
f5f0: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
f600: 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
f610: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
f620: 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
f630: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
f640: 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
f650: 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
f660: 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
f670: 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
f680: 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74   smaller.** mult
f690: 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20  iple of 8.  See 
f6a0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f  also: [SQLITE_CO
f6b0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c  NFIG_LOOKASIDE]<
f6c0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
f6d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f6e0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f6f0: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f  ASIDE    1001  /
f700: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
f710: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
f720: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
f730: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
f740: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
f750: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f760: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
f770: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
f780: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
f790: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
f7a0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
f7b0: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
f7c0: 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
f7d0: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
f7e0: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
f7f0: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
f800: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
f810: 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
f820: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
f830: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
f840: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
f850: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
f860: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
f870: 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
f880: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
f890: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
f8a0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
f8b0: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
f8c0: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
f8d0: 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
f8e0: 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
f8f0: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
f900: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
f910: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
f920: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
f930: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
f940: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
f950: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
f960: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
f970: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
f980: 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
f990: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
f9a0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
f9b0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
f9c0: 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
f9d0: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
f9e0: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
f9f0: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
fa00: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
fa10: 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
fa20: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
fa30: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
fa40: 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
fa50: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
fa60: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
fa70: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
fa80: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
fa90: 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63  ent.  ^If no suc
faa0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
fab0: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
fac0: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
fad0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fae0: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
faf0: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
fb00: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
fb10: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
fb20: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
fb30: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
fb40: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69  nserted.** row i
fb50: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
fb60: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
fb70: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
fb80: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  r is running..**
fb90: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
fba0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
fbb0: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
fbc0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
fbd0: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20  tine.** reverts 
fbe0: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
fbf0: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
fc00: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69  e the trigger fi
fc10: 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  red.)^.**.** ^An
fc20: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
fc30: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
fc40: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
fc50: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
fc60: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
fc70: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
fc80: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
fc90: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
fca0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
fcb0: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
fcc0: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
fcd0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
fce0: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
fcf0: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
fd00: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
fd10: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
fd20: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
fd30: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
fd40: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
fd50: 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
fd60: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
fd70: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
fd80: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
fd90: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
fda0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
fdb0: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
fdc0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
fdd0: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
fde0: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
fdf0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
fe00: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
fe10: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
fe20: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
fe30: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
fe40: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
fe50: 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
fe60: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
fe70: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
fe80: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
fe90: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
fea0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
feb0: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
fec0: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
fed0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
fee0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
fef0: 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
ff00: 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
ff10: 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
ff20: 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
ff30: 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
ff40: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
ff50: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
ff60: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
ff70: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
ff80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ff90: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
ffa0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
ffb0: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
ffc0: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
ffd0: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
ffe0: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
fff0: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
10000 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
10010 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
10020 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
10030 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
10040 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
10050 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
10060 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
10070 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
10080 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
10090 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
100a0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
100b0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
100c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
100d0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
100e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
100f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
10100 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
10110 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
10120 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
10130 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
10140 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
10150 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
10160 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10170 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
10180 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
10190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
101a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
101b0 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
101c0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
101d0 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  ^(Only changes t
101e0 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
101f0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
10200 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
10210 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
10220 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
10230 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
10240 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
10250 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
10260 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e  gers or [foreign
10270 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
10280 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e  e not counted.)^
10290 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   Use the.** [sql
102a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
102b0 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74  es()] function t
102c0 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
102d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
102e0 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20  es.** including 
102f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
10300 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66  y triggers and f
10310 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
10320 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67  ns..**.** ^Chang
10330 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
10340 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
10350 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
10360 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
10370 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
10380 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
10390 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
103a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22  ted..**.** ^(A "
103b0 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
103c0 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
103d0 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
103e0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
103f0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
10400 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
10410 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
10420 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
10430 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
10440 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
10450 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
10460 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
10470 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
10480 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
10490 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
104a0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
104b0 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
104c0 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
104d0 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a  ow changes.)^.**
104e0 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
104f0 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
10500 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
10510 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
10520 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
10530 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52   script of a [CR
10540 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
10550 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73  rigger]. .** Mos
10560 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
10570 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
10580 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
10590 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
105a0 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
105b0 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
105c0 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
105d0 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
105e0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
105f0 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
10600 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
10610 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
10620 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
10630 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
10640 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
10650 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
10660 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
10670 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b  **.** ^Calling [
10680 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
10690 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
106a0 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
106b0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
106c0 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
106d0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
106e0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
106f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
10700 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
10710 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
10720 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
10730 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10740 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
10750 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
10760 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
10770 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75  text..**.** ^Thu
10780 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
10790 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
107a0 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
107b0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
107c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
107d0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
107e0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
107f0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10800 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
10810 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
10820 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e  level.  ^(Within
10830 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
10840 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
10850 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
10860 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
10870 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
10880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
10890 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
108a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
108b0 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
108c0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
108d0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
108e0 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
108f0 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
10900 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
10910 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
10920 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
10930 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
10940 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
10950 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
10960 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
10970 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a  n context.)^.**.
10980 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
10990 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
109a0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
109b0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
109c0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
109d0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
109e0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
109f0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
10a00 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
10a10 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
10a20 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
10a30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
10a40 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
10a50 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
10a60 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
10a70 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
10a80 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
10a90 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
10aa0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
10ab0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
10ac0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
10ad0 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
10ae0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
10af0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
10b00 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
10b10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
10b20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
10b30 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
10b40 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
10b50 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
10b60 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
10b70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10b80 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
10b90 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
10ba0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
10bb0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10bc0 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
10bd0 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
10be0 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
10bf0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
10c00 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
10c10 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
10c20 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
10c30 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
10c40 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
10c50 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
10c60 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
10c70 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
10c80 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
10c90 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
10ca0 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
10cb0 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
10cc0 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
10cd0 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
10ce0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
10cf0 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
10d00 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
10d10 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
10d20 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
10d30 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
10d40 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
10d50 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
10d60 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
10d70 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
10d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10d90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
10da0 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
10db0 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
10dc0 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
10dd0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
10de0 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
10df0 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
10e00 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
10e10 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
10e20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
10e30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
10e40 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
10e50 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
10e60 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
10e70 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
10e80 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
10e90 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
10ea0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
10eb0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
10ec0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
10ed0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
10ee0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
10ef0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
10f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
10f10 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
10f20 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
10f30 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
10f40 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
10f50 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
10f60 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
10f70 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
10f80 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
10f90 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
10fa0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
10fb0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
10fc0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
10fd0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
10fe0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
10ff0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
11000 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
11010 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
11020 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
11030 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
11040 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
11050 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
11060 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
11070 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
11080 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
11090 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
110a0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
110b0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
110c0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
110d0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
110e0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
110f0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
11100 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
11110 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
11120 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
11130 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
11140 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
11150 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
11160 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
11170 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
11180 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
11190 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
111a0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
111b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
111c0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
111d0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
111e0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
111f0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
11200 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
11210 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
11220 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
11230 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
11240 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
11250 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
11260 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
11270 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
11280 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
11290 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
112a0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
112b0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
112c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
112d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
112e0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
112f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11300 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
11310 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
11320 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
11330 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
11340 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
11350 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
11360 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
11370 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
11380 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
11390 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
113a0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
113b0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
113c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
113d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
113e0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
113f0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
11400 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
11410 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
11420 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
11430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
11440 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
11450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
11460 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
11470 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
11480 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11490 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
114a0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
114b0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
114c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
114d0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
114e0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
114f0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
11500 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
11510 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
11520 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
11530 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
11540 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
11550 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
11560 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
11570 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
11580 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
11590 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
115a0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
115b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
115c0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
115d0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
115e0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
115f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
11600 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
11610 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
11620 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
11630 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
11640 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
11650 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11660 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
11670 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
11680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11690 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
116a0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
116b0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
116c0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
116d0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
116e0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
116f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11700 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
11710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
11720 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
11730 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
11740 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
11750 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
11760 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
11770 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
11780 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
11790 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
117a0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
117b0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
117c0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
117d0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
117e0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
117f0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
11800 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
11810 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
11820 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
11830 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
11840 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
11850 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
11860 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
11870 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
11880 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
11890 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
118a0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
118b0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
118c0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
118d0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
118e0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
118f0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
11900 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
11910 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
11920 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
11930 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
11940 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
11950 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
11960 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
11970 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
11980 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
11990 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
119a0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
119b0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
119c0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
119d0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
119e0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
119f0 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
11a00 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
11a10 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
11a20 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
11a30 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
11a40 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
11a50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
11a60 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
11a70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
11a80 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
11a90 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11aa0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
11ab0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
11ac0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
11ad0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
11ae0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
11af0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
11b00 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
11b10 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
11b20 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
11b30 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
11b40 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
11b50 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
11b60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
11b70 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
11b80 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
11b90 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
11ba0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
11bb0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11bc0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
11bd0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
11be0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
11bf0 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
11c00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11c10 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
11c20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
11c30 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
11c40 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
11c50 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
11c60 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
11c70 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
11c80 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
11c90 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
11ca0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
11cb0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
11cc0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
11cd0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
11ce0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
11cf0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
11d00 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
11d10 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
11d20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
11d30 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
11d40 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
11d50 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
11d60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
11d70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
11d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
11d90 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
11da0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
11db0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
11dc0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
11dd0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
11de0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
11df0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
11e00 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
11e10 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
11e20 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
11e30 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
11e40 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
11e50 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
11e60 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
11e70 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
11e80 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
11e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
11ea0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
11eb0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
11ec0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
11ed0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
11ee0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
11ef0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
11f00 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
11f10 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
11f20 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
11f30 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
11f40 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
11f50 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
11f60 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
11f70 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
11f80 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
11f90 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
11fa0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
11fb0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
11fc0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
11fd0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
11fe0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
11ff0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
12000 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
12010 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
12020 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
12030 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
12040 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
12050 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
12060 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
12070 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
12080 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
12090 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
120a0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
120b0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
120c0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
120d0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
120e0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
120f0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
12100 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
12110 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12120 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
12130 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
12140 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
12150 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
12160 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
12170 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
12180 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
12190 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
121a0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
121b0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
121c0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
121d0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
121e0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
121f0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
12200 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
12210 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
12220 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
12230 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
12240 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
12250 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
12260 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
12270 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
12280 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
12290 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
122a0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
122b0 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
122c0 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
122d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
122e0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
122f0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
12300 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
12310 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
12320 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
12330 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
12340 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
12350 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
12360 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
12370 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
12380 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
12390 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
123a0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
123b0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
123c0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
123d0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
123e0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
123f0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
12400 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
12410 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
12420 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
12430 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
12440 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
12450 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
12460 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
12470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
12480 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
12490 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
124a0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
124b0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
124c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
124d0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
124e0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
124f0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
12500 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
12510 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
12520 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
12530 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
12540 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
12550 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
12560 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
12570 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
12580 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
12590 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
125a0 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
125b0 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
125c0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
125d0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
125e0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
125f0 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
12600 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
12610 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
12620 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
12630 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
12640 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
12650 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
12660 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
12670 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
12680 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
12690 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
126a0 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
126b0 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
126c0 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
126d0 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
126e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
126f0 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
12700 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
12710 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
12720 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
12730 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
12740 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
12750 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
12760 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
12770 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
12780 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
12790 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
127a0 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
127b0 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
127c0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
127d0 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
127e0 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
127f0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
12800 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
12810 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
12820 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
12830 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
12840 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
12850 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
12860 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
12870 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
12880 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
12890 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
128a0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
128b0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
128c0 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
128d0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
128e0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
128f0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
12900 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
12910 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
12920 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
12930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12940 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
12950 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
12960 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
12970 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
12980 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
12990 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
129a0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
129b0 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
129c0 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
129d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
129e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
129f0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
12a00 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
12a10 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
12a20 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
12a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
12a40 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
12a50 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
12a60 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
12a70 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
12a80 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
12a90 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
12aa0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
12ab0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
12ac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
12ad0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
12ae0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
12af0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
12b00 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
12b10 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
12b20 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
12b30 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
12b40 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
12b50 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
12b60 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
12b70 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
12b80 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
12b90 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
12ba0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
12bb0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
12bc0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
12bd0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
12be0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
12bf0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
12c00 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
12c10 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
12c20 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
12c30 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
12c40 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
12c50 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
12c60 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
12c70 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
12c80 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
12c90 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
12ca0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
12cb0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
12cc0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
12cd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
12ce0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
12cf0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
12d00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
12d10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
12d20 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
12d30 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
12d40 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
12d50 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
12d60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
12d70 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
12d80 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
12d90 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
12da0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
12db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12dc0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
12dd0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
12de0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
12df0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
12e00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
12e10 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
12e20 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
12e30 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
12e40 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
12e50 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
12e60 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  red.)^.*/.int sq
12e70 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
12e80 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
12e90 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
12ea0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
12eb0 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
12ec0 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
12ed0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
12ee0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
12ef0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
12f00 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
12f10 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
12f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
12f30 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
12f40 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
12f50 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
12f60 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
12f70 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
12f80 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
12f90 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
12fa0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
12fb0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
12fc0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
12fd0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
12fe0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
12ff0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
13000 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
13010 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
13020 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
13030 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
13040 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
13050 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
13060 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
13070 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
13080 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
13090 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
130a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
130b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
130c0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
130d0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
130e0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
130f0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
13100 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
13110 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
13120 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
13130 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
13140 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
13150 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
13160 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
13170 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
13180 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
13190 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
131a0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
131b0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
131c0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
131d0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
131e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
131f0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
13200 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
13210 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
13220 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
13230 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
13240 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
13250 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
13260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13270 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
13280 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
13290 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
132a0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
132b0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
132c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
132d0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
132e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
132f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
13300 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
13310 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
13320 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
13330 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
13340 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
13350 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
13360 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13370 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
13380 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
13390 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
133a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
133b0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
133c0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
133d0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
133e0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
133f0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
13400 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13410 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
13420 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
13430 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
13440 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
13450 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
13460 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
13470 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
13480 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
13490 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
134a0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
134b0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
134c0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
134d0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
134e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
134f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
13500 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
13510 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
13520 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13530 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
13540 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13550 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
13560 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
13570 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
13580 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
13590 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
135a0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
135b0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
135c0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
135d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
135e0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
135f0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13600 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
13610 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13620 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e  ckquote>.**.** ^
13630 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
13640 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
13650 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
13660 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
13670 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
13680 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
13690 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
136a0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
136b0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
136c0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
136d0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
136e0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
136f0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
13700 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
13710 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
13720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
13730 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
13740 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
13750 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13760 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 6c  e(),.** it shoul
13770 64 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  d pass the resul
13780 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
13790 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
137a0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
137b0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
137c0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
137d0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
137e0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
137f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
13800 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
13810 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
13820 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
13830 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
13840 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
13850 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
13860 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
13870 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
13880 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
13890 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
138a0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
138b0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
138c0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
138d0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  ^(The sqlite3_ge
138e0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
138f0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
13900 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
13910 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
13920 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
13930 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
13940 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
13950 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
13960 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
13970 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
13980 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
13990 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
139a0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
139b0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
139c0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
139d0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
139e0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
139f0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
13a00 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
13a10 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
13a20 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
13a30 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
13a40 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
13a50 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
13a60 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
13a70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
13a80 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e  rmsg()].)^.*/.in
13a90 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
13aa0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
13ab0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
13ac0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
13ad0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
13ae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
13af0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
13b00 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
13b10 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
13b20 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
13b30 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
13b40 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
13b50 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
13b60 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
13b70 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
13b80 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
13b90 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
13ba0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
13bb0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
13bc0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
13bd0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
13be0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
13bf0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
13c00 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
13c10 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
13c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
13c30 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
13c40 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
13c50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
13c60 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
13c70 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
13c80 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
13c90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
13ca0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
13cb0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
13cc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
13cd0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
13ce0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
13cf0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
13d00 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
13d10 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
13d20 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
13d30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
13d40 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
13d50 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
13d60 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
13d70 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
13d80 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
13d90 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
13da0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13db0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
13dc0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
13dd0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
13de0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
13df0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
13e00 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
13e10 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
13e20 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f  ** ^(In sqlite3_
13e30 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
13e40 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
13e50 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
13e60 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
13e70 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
13e80 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
13e90 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
13ea0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
13eb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
13ec0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
13ed0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
13ee0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
13ef0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
13f00 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
13f10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
13f20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
13f30 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
13f40 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
13f50 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
13f60 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
13f70 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
13f80 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
13f90 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
13fa0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
13fb0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
13fc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
13fd0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
13fe0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
13ff0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
14000 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
14010 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
14020 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
14030 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
14040 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
14050 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
14060 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
14070 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
14080 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
14090 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
140a0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
140b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
140c0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
140d0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
140e0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
140f0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
14100 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
14110 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
14120 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
14130 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
14140 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
14150 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
14160 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
14170 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
14180 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
14190 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
141a0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
141b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
141c0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
141d0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
141e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
141f0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
14200 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
14210 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
14220 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
14230 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
14240 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
14250 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
14260 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
14270 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
14280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
14290 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
142a0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
142b0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
142c0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
142d0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
142e0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
142f0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
14300 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
14310 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
14320 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
14330 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
14340 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
14350 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
14360 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
14370 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
14380 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
14390 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
143a0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
143b0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
143c0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
143d0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
143e0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
143f0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
14400 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
14410 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
14420 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
14430 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
14440 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
14450 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
14460 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
14470 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
14480 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
14490 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
144a0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
144b0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
144c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
144d0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
144e0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
144f0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
14500 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14510 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
14520 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
14530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
14540 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
14550 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14560 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
14570 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
14580 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
14590 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
145a0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
145b0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
145c0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
145d0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
145e0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
145f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14600 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
14610 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
14620 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
14630 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
14640 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
14650 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
14660 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
14670 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
14680 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
14690 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
146a0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
146b0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
146c0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
146d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
146e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
146f0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
14700 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
14710 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
14720 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
14730 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
14740 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
14750 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
14760 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
14770 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
14780 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
14790 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
147a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
147b0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
147c0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
147d0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
147e0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
147f0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
14800 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
14810 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
14820 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
14830 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
14840 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
14850 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
14860 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
14870 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
14880 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
14890 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
148a0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
148b0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
148c0 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
148d0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
148e0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
148f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
14900 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
14910 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
14920 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
14930 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
14940 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
14950 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
14960 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14970 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14980 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
14990 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
149a0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
149b0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
149c0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
149d0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
149e0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
149f0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
14a00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14a10 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
14a20 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
14a30 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
14a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
14a50 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
14a60 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
14a70 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
14a80 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
14a90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
14aa0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
14ab0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
14ac0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
14ad0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
14ae0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
14af0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
14b00 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
14b10 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
14b20 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
14b30 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
14b40 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
14b50 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
14b60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
14b70 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
14b80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
14b90 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
14ba0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
14bb0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
14bc0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
14bd0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
14be0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14bf0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14c00 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
14c10 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
14c20 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
14c30 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
14c40 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
14c50 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
14c60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14c70 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
14c80 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
14c90 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
14ca0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
14cb0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
14cc0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
14cd0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
14ce0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
14cf0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
14d00 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
14d10 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
14d20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14d30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
14d40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
14d50 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
14d60 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
14d70 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
14d80 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
14d90 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
14da0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
14db0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
14dc0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
14dd0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
14de0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
14df0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
14e00 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
14e10 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
14e20 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
14e30 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
14e40 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
14e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
14e60 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
14e70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
14e80 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
14e90 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
14ea0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
14eb0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
14ec0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14ed0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
14ee0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
14ef0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
14f00 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
14f10 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
14f20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
14f30 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
14f40 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
14f50 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
14f60 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
14f70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
14f80 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
14f90 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
14fa0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
14fb0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
14fc0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
14fd0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
14fe0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
14ff0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
15000 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
15010 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
15020 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
15030 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
15040 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
15050 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
15060 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
15070 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
15080 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
15090 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
150a0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
150b0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
150c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
150d0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
150e0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
150f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
15100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15110 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
15120 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15130 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
15140 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
15150 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
15160 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
15170 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
15180 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
15190 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
151a0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
151b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
151c0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
151d0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
151e0 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
151f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15200 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15210 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
15220 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
15230 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
15240 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
15250 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
15260 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
15270 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
15280 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15290 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
152a0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
152b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
152c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
152d0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
152e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
152f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
15300 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
15310 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
15320 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
15330 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
15340 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15350 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
15360 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
15370 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
15380 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
15390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
153a0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
153b0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
153c0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
153d0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
153e0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
153f0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
15400 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
15410 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
15420 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
15430 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
15440 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
15450 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
15460 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
15470 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
15480 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15490 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
154a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
154b0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
154c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
154d0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
154e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
154f0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
15500 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
15510 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
15520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
15530 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
15540 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
15550 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
15560 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
15570 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
15580 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
15590 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
155a0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
155b0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
155c0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
155d0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
155e0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
155f0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
15600 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
15610 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
15620 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
15630 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
15640 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
15650 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
15660 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
15670 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
15680 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
15690 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69  ed..**.** The Wi
156a0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
156b0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
156c0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
156d0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
156e0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
156f0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
15700 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
15710 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
15720 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
15730 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
15740 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
15750 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
15760 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
15770 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
15780 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
15790 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
157a0 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
157b0 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
157c0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
157d0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
157e0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
157f0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
15800 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
15810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
15820 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
15830 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15840 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
15850 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
15860 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
15870 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
15880 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
15890 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
158a0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
158b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
158c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
158d0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
158e0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
158f0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
15900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15910 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
15920 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
15930 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
15940 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
15950 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
15960 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
15970 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
15980 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15990 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
159a0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
159b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
159c0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
159d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
159e0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
159f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
15a00 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
15a10 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
15a20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
15a30 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
15a40 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
15a50 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
15a60 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
15a70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
15a80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
15a90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
15aa0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
15ab0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
15ac0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
15ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15ae0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
15af0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
15b00 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
15b10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
15b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
15b30 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
15b40 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
15b50 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
15b60 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
15b70 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
15b80 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
15b90 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
15ba0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
15bb0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
15bc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
15bd0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
15be0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
15bf0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
15c00 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
15c10 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
15c20 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
15c30 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
15c40 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15c50 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
15c60 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
15c70 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
15c80 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
15c90 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
15ca0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
15cb0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
15cc0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
15cd0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
15ce0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
15cf0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
15d00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
15d10 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
15d20 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
15d30 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
15d40 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
15d50 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
15d60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
15d70 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
15d80 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
15d90 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
15da0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15db0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
15dc0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
15dd0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
15de0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15df0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
15e00 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
15e10 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
15e20 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
15e30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
15e40 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
15e50 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
15e60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
15e70 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
15e80 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
15e90 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
15ea0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
15eb0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
15ec0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
15ed0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
15ee0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
15ef0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
15f00 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
15f10 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
15f20 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
15f30 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
15f40 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
15f50 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
15f60 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
15f70 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
15f80 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
15f90 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
15fa0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
15fb0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
15fc0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
15fd0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
15fe0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
15ff0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
16000 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
16010 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
16020 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
16030 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
16040 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
16050 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
16060 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
16070 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
16080 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
16090 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
160a0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
160b0 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
160c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
160d0 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
160e0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
160f0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
16100 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
16110 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
16120 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
16130 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
16140 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
16150 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
16160 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
16170 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
16180 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
16190 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
161a0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
161b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
161c0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
161d0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
161e0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
161f0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
16200 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
16210 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
16220 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
16230 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
16240 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
16250 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
16260 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16270 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
16280 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
16290 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
162a0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
162b0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
162c0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
162d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
162e0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
162f0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
16300 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
16310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
16320 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
16330 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
16340 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
16350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
16360 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
16370 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
16380 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
16390 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
163a0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
163b0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
163c0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
163d0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
163e0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
163f0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
16400 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16410 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
16420 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
16430 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
16440 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16450 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
16460 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
16470 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
16480 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
16490 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
164a0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
164b0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
164c0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
164d0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
164e0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
164f0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
16500 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
16510 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
16520 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
16530 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
16540 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
16550 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16560 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
16570 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
16580 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
16590 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
165a0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
165b0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
165c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
165d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
165e0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
165f0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
16600 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
16610 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
16620 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
16630 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
16640 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
16650 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
16660 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
16670 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
16680 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
16690 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
166a0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
166b0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
166c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
166d0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
166e0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
166f0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
16700 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
16710 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
16720 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
16730 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
16740 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
16750 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
16760 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16770 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16780 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
16790 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
167a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
167b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
167c0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
167d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
167e0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
167f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
16800 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
16810 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
16820 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
16830 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
16840 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
16850 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
16860 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
16870 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
16880 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
16890 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
168a0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
168b0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
168c0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
168d0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
168e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
168f0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
16900 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
16910 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
16920 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
16930 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16940 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
16950 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
16960 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
16970 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
16980 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
16990 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
169a0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
169b0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
169c0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
169d0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
169e0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
169f0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
16a00 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
16a10 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
16a20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
16a30 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
16a40 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
16a50 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
16a60 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
16a70 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
16a80 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
16a90 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
16aa0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
16ab0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
16ac0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
16ad0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
16ae0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
16af0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
16b00 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
16b10 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
16b20 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
16b30 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
16b40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
16b50 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
16b60 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
16b70 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
16b80 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
16b90 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
16ba0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
16bb0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
16bc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
16bd0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
16be0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
16bf0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
16c00 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
16c10 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
16c20 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
16c30 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
16c40 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
16c50 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
16c60 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
16c70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
16c80 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
16c90 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
16ca0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
16cb0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
16cc0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
16cd0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
16ce0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
16cf0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
16d00 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
16d10 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
16d20 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
16d30 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
16d40 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
16d50 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
16d60 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
16d70 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
16d80 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
16d90 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
16da0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
16db0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
16dc0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
16dd0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
16de0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
16df0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
16e00 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
16e10 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
16e20 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
16e30 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
16e40 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
16e50 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
16e60 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
16e70 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
16e80 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
16e90 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
16ea0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
16eb0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
16ec0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
16ed0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
16ee0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
16ef0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
16f00 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
16f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
16f20 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
16f30 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
16f40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16f50 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
16f60 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
16f70 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
16f80 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
16f90 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
16fa0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
16fb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
16fc0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
16fd0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
16fe0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16ff0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
17000 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
17010 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
17020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17030 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
17040 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17050 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
17060 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
17070 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
17080 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
17090 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
170a0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
170b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
170c0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
170d0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
170e0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
170f0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
17100 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
17110 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
17120 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
17130 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
17140 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
17150 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
17160 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
17170 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
17180 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
17190 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
171a0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
171b0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
171c0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
171d0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
171e0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
171f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
17200 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
17210 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
17220 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17230 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
17240 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
17250 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
17260 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
17270 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
17280 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
17290 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
172a0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
172b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
172c0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
172d0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
172e0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
172f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
17300 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
17310 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
17320 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
17330 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
17340 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
17350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
17360 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
17370 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
17380 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
17390 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
173a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
173b0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
173c0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
173d0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
173e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
173f0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
17400 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
17410 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17420 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
17430 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
17440 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
17450 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
17460 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
17470 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
17480 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
17490 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
174a0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
174b0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
174c0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
174d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
174e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
174f0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
17500 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
17510 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
17520 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
17530 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
17540 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
17550 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17560 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
17570 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17580 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
17590 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
175a0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
175b0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
175c0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
175d0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
175e0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
175f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17600 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
17610 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
17620 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
17630 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
17640 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
17650 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
17660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
17670 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
17680 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17690 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
176a0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
176b0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
176c0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
176d0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
176e0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
176f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
17700 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
17710 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
17720 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
17730 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
17740 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
17750 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
17760 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
17770 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
17780 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
17790 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
177a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
177b0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
177c0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
177d0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
177e0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
177f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
17800 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
17810 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
17820 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17830 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
17840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17850 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
17860 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
17870 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
17880 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
17890 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
178a0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
178b0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
178c0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
178d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
178e0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
178f0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
17900 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
17910 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
17920 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
17930 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
17940 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
17950 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
17960 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
17970 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
17980 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
17990 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
179a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
179b0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
179c0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
179d0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
179e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
179f0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
17a00 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
17a10 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17a20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17a30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
17a40 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
17a50 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17a60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17a70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17a80 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
17a90 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
17aa0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
17ab0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ad0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
17ae0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
17af0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17b00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17b20 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
17b30 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
17b40 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
17b50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17b60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b70 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
17b80 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
17b90 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
17ba0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17bb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17bc0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
17bd0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
17be0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
17bf0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17c10 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
17c20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
17c30 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
17c40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
17c60 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
17c70 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
17c80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
17c90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
17cb0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
17cc0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
17cd0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
17ce0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17d00 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
17d10 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
17d20 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17d30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17d40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17d50 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
17d60 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
17d70 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
17d80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17d90 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
17da0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
17db0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
17dc0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17dd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17de0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
17df0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
17e00 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
17e10 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
17e20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17e30 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
17e40 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
17e50 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
17e60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17e70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17e80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
17e90 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
17ea0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
17eb0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
17ec0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17ed0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
17ee0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
17ef0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
17f00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17f10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17f20 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
17f30 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
17f40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17f50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17f60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17f70 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
17f80 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
17f90 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
17fa0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
17fb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17fc0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
17fd0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
17fe0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17ff0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
18000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18010 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
18020 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
18030 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
18040 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18060 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
18070 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
18080 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
18090 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
180a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
180b0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
180c0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
180d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
180e0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
180f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
18100 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
18110 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
18120 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
18130 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
18150 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
18160 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
18170 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
18180 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
181a0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
181b0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
181c0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
181d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
181e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
181f0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
18200 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
18210 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18220 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18230 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
18240 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
18250 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
18260 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18270 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18280 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18290 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
182a0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
182b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
182c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
182d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
182e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
182f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18300 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
18310 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18320 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
18330 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
18340 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
18350 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
18360 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
18370 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
18380 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
18390 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
183a0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
183b0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
183c0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
183d0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
183e0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
183f0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
18400 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
18410 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
18420 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
18430 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
18440 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
18450 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
18460 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
18470 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
18480 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
18490 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
184a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
184b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
184c0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
184d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
184e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
184f0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
18500 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
18510 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
18520 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
18530 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
18540 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
18550 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18560 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
18570 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
18580 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
18590 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
185a0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
185b0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
185c0 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
185d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
185e0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
185f0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
18600 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
18610 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
18620 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
18630 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
18640 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
18650 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
18660 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
18670 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
18680 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
18690 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
186a0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
186b0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
186c0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
186d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
186e0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
186f0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
18700 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
18710 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
18720 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
18730 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
18740 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
18750 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
18760 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
18770 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  run..*/.void *sq
18780 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
18790 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
187a0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
187b0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
187c0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
187d0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
187e0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
187f0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
18800 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
18810 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
18820 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
18830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18840 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
18850 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
18860 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18870 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c  configures a cal
18880 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d  lback function -
18890 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73   the.** progress
188a0 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74   callback - that
188b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
188c0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
188d0 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  long.** running 
188e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
188f0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
18900 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a  te3_step()] and.
18910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
18920 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78  table()].  An ex
18930 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
18940 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
18950 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
18960 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
18970 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
18980 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
18990 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
189a0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
189b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
189c0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
189d0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
189e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
189f0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
18a00 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
18a10 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
18a20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
18a30 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
18a40 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
18a50 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
18a60 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
18a70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18a80 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
18a90 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
18aa0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
18ab0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
18ac0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
18ad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
18ae0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
18af0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
18b00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
18b10 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
18b20 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
18b30 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
18b40 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
18b50 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18b60 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
18b70 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
18b80 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18b90 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
18ba0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
18bb0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
18bc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18bd0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
18be0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f  atabase file who
18bf0 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e  se name is given
18c00 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   by the.** filen
18c10 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
18c20 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
18c30 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
18c40 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
18c50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
18c60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
18c70 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
18c80 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
18c90 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
18ca0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
18cb0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
18cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18cd0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
18ce0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
18cf0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
18d00 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
18d10 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
18d20 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
18d30 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
18d40 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
18d50 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
18d60 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
18d70 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
18d80 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
18d90 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
18da0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
18db0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
18dc0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
18dd0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
18de0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
18df0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
18e00 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
18e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
18e20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
18e30 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
18e40 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
18e50 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
18e60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
18e70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
18e80 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
18e90 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
18ea0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
18eb0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
18ec0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
18ed0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
18ee0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
18ef0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
18f00 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
18f10 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
18f20 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
18f30 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
18f40 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
18f50 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
18f60 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
18f70 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
18f80 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
18f90 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
18fa0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
18fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
18fc0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
18fd0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
18fe0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
18ff0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
19000 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
19010 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19020 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
19030 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
19040 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
19050 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
19060 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
19070 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
19080 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
19090 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
190a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
190b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
190c0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
190d0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
190e0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
190f0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19100 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
19110 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
19120 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
19130 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
19140 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
19150 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
19160 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
19170 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
19180 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
19190 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
191a0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
191b0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
191c0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
191d0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
191e0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
191f0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
19200 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
19210 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  .** and/or [SQLI
19220 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
19230 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  ACHE] flags:)^.*
19240 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
19250 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19260 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
19270 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
19280 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
19290 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
192a0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
192b0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
192c0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
192d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
192e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
192f0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
19300 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
19310 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
19320 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19330 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
19340 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
19350 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
19360 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
19370 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
19380 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
19390 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
193a0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
193b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
193c0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
193d0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
193e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
193f0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
19400 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
19410 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
19420 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
19430 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
19440 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
19450 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
19460 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
19470 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73  , and is creates
19480 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65   it if.** it doe
19490 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
194a0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
194b0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
194c0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
194d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
194e0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
194f0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
19500 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
19510 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
19520 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19530 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
19540 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
19550 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
19560 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f  n above or one o
19570 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  f the combinatio
19580 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63  ns shown above c
19590 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20  ombined.** with 
195a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
195b0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
195c0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
195d0 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  X],.** [SQLITE_O
195e0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
195f0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
19600 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
19610 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e  ] flags,.** then
19620 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
19630 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
19640 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
19650 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
19660 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
19670 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19680 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
19690 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
196a0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
196b0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
196c0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
196d0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
196e0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
196f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
19700 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
19710 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
19720 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
19730 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
19740 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19750 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
19760 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
19770 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
19780 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
19790 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
197a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
197b0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
197c0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
197d0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
197e0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
197f0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
19800 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
19810 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
19820 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
19830 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
19840 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
19850 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
19860 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
19870 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
19880 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19890 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
198a0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
198b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
198c0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
198d0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
198e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
198f0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
19900 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
19910 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
19920 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
19930 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
19940 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
19950 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
19960 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
19970 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
19980 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
19990 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
199a0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
199b0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
199c0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
199d0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
199e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
199f0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
19a00 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
19a10 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
19a20 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
19a30 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
19a40 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
19a50 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
19a60 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
19a70 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
19a80 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
19a90 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
19aa0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
19ab0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
19ac0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
19ad0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
19ae0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
19af0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
19b00 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
19b10 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
19b20 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
19b30 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
19b40 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
19b50 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
19b60 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
19b70 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
19b80 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
19b90 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
19ba0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
19bb0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
19bc0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
19bd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19be0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
19bf0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
19c00 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19c10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
19c20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
19c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
19c40 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
19c50 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
19c60 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
19c70 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
19c80 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
19c90 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
19ca0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
19cb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
19cc0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
19cd0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
19ce0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
19cf0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
19d00 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
19d10 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
19d20 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
19d30 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
19d40 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
19d50 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
19d60 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19d70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
19d80 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
19d90 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
19da0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
19db0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
19dc0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
19dd0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
19de0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
19df0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
19e00 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
19e10 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
19e20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
19e30 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
19e40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a  3_open_v2()..*/.
19e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
19e60 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
19e70 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
19e80 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
19e90 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
19ea0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
19eb0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
19ec0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
19ed0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
19ee0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
19ef0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
19f00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
19f10 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
19f20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
19f30 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
19f40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
19f50 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
19f60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19f70 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
19f80 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
19f90 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
19fa0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
19fb0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
19fc0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
19fd0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
19fe0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
19ff0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1a000 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1a010 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1a020 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1a030 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1a040 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1a050 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1a060 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
1a070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a080 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1a090 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1a0a0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1a0b0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1a0c0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a0d0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1a0e0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1a0f0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1a100 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1a110 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1a120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1a130 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1a140 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1a150 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a160 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1a170 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1a180 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1a190 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1a1a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
1a1b0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1a1c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
1a1d0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1a1e0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
1a1f0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
1a200 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
1a210 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a220 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
1a230 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a240 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
1a250 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1a260 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1a270 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1a280 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1a290 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1a2a0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1a2b0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1a2c0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1a2d0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1a2e0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
1a2f0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1a300 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1a310 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1a320 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1a330 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1a340 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1a350 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1a360 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1a370 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1a380 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1a390 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1a3a0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1a3b0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1a3c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1a3d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1a3e0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
1a3f0 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
1a400 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1a410 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
1a420 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
1a430 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
1a440 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
1a450 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
1a460 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a470 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
1a480 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
1a490 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
1a4a0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
1a4b0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
1a4c0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
1a4d0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
1a4e0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
1a4f0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
1a500 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
1a510 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
1a520 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
1a530 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
1a540 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
1a550 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
1a560 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
1a570 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1a580 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
1a590 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1a5a0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
1a5b0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1a5c0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
1a5d0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
1a5e0 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
1a5f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1a600 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
1a610 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
1a620 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
1a630 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
1a640 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
1a650 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
1a660 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1a670 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1a680 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1a690 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1a6a0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1a6b0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1a6c0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1a6d0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1a6e0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1a6f0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1a700 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1a710 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
1a720 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1a730 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
1a740 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
1a750 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
1a760 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
1a770 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
1a780 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
1a790 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1a7a0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
1a7b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a7c0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
1a7d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
1a7e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
1a7f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
1a800 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1a810 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
1a820 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
1a830 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
1a840 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
1a850 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
1a860 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
1a870 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
1a880 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
1a890 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
1a8a0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1a8b0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
1a8c0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
1a8d0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
1a8e0 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
1a8f0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
1a900 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
1a910 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1a920 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
1a930 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
1a940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a950 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
1a960 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
1a970 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
1a980 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
1a990 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
1a9a0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1a9b0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
1a9c0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
1a9d0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
1a9e0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1a9f0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
1aa00 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1aa10 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
1aa20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1aa30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1aa40 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
1aa50 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
1aa60 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
1aa70 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1aa80 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
1aa90 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1aaa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1aab0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
1aac0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
1aad0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
1aae0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
1aaf0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
1ab00 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1ab10 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
1ab20 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1ab30 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
1ab40 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
1ab50 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
1ab60 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
1ab70 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1ab80 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
1ab90 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
1aba0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
1abb0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
1abc0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
1abd0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
1abe0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1abf0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
1ac00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
1ac10 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
1ac20 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
1ac30 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1ac40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1ac50 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
1ac60 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
1ac70 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
1ac80 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
1ac90 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
1aca0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
1acb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1acc0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
1acd0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
1ace0 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
1acf0 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
1ad00 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  limit.)^.**.** ^
1ad10 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1ad20 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1ad30 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1ad40 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1ad50 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69  * ^(For the limi
1ad60 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51  t category of SQ
1ad70 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74  LITE_LIMIT_XYZ t
1ad80 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
1ad90 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
1ada0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
1adb0 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69   by a compile-ti
1adc0 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  me C preprocesso
1add0 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a  r macro named .*
1ade0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
1adf0 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20  TE_MAX_XYZ]..** 
1ae00 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1ae10 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1ae20 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1ae30 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
1ae40 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
1ae50 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
1ae60 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1ae70 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
1ae80 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
1ae90 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
1aea0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  nd..**.** Run-ti
1aeb0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1aec0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1aed0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1aee0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1aef0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1af00 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1af10 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1af20 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1af30 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1af40 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1af50 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1af60 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1af70 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1af80 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
1af90 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
1afa0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
1afb0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
1afc0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
1afd0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
1afe0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
1aff0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
1b000 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
1b010 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
1b020 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
1b030 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
1b040 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
1b050 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
1b060 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
1b070 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
1b080 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
1b090 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
1b0a0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
1b0b0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
1b0c0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
1b0d0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
1b0e0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
1b0f0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
1b100 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b110 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
1b120 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
1b130 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
1b140 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
1b150 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
1b160 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
1b170 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
1b180 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
1b190 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
1b1a0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
1b1b0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
1b1c0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
1b1d0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
1b1e0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
1b1f0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1b200 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
1b210 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1b220 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1b230 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1b240 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1b250 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1b260 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
1b270 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
1b280 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
1b290 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1b2a0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1b2b0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
1b2c0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
1b2d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
1b2e0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
1b2f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b300 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
1b310 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
1b320 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
1b330 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
1b340 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
1b350 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
1b360 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
1b370 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
1b380 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
1b390 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
1b3a0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  >.** ^(<dt>SQLIT
1b3b0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1b3c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1b3d0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1b3e0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
1b3f0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c  B or table row.<
1b400 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b410 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
1b420 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
1b430 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b440 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
1b450 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
1b460 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
1b470 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1b480 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
1b490 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1b4a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1b4b0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
1b4c0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
1b4d0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
1b4e0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1b4f0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
1b500 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1b510 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1b520 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
1b530 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
1b540 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
1b550 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1b560 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1b570 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1b580 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1b590 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
1b5a0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
1b5b0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
1b5c0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1b5d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1b5e0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
1b5f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1b600 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1b610 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1b620 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1b630 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1b640 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1b650 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
1b660 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1b670 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
1b680 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
1b690 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
1b6a0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
1b6b0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
1b6c0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1b6d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1b6e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
1b6f0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
1b700 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1b710 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
1b720 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
1b730 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1b740 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1b750 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
1b760 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b770 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
1b780 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
1b790 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
1b7a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  /dd>.**.** ^(<dt
1b7b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
1b7c0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1b7d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1b7e0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1b7f0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
1b800 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1b810 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
1b820 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
1b830 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1b850 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
1b860 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1b870 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1b880 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e   variables in an
1b890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1b8a0 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f  hat can.** be bo
1b8b0 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  und.</dd>)^.**.*
1b8c0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1b8d0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
1b8e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1b8f0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1b900 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
1b910 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
1b920 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
1b930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1b940 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
1b950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
1b960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1b970 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
1b980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1b990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b9a0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
1b9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b9c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
1b9d0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1b9e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1b9f0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
1ba00 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1ba10 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1ba20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
1ba30 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1ba40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ba50 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
1ba60 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1ba70 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
1ba80 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
1ba90 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
1baa0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
1bab0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
1bac0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1bad0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
1bae0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
1baf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1bb00 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
1bb10 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
1bb20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
1bb30 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
1bb40 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a         10../*.**
1bb50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1bb60 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
1bb70 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
1bb80 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
1bb90 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
1bba0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
1bbb0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
1bbc0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
1bbd0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
1bbe0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
1bbf0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
1bc00 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
1bc10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1bc20 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
1bc30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1bc40 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
1bc50 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
1bc60 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
1bc70 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
1bc80 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1bc90 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
1bca0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1bcb0 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
1bcc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
1bcd0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
1bce0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
1bcf0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1bd00 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
1bd10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
1bd20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
1bd30 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
1bd40 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1bd50 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
1bd60 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
1bd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bd80 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
1bd90 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
1bda0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1bdb0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
1bdc0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
1bdd0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
1bde0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
1bdf0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1be00 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
1be10 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
1be20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
1be30 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1be40 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
1be50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1be60 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1be70 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
1be80 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
1be90 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
1bea0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
1beb0 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
1bec0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
1bed0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
1bee0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
1bef0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
1bf00 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
1bf10 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
1bf20 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
1bf30 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
1bf40 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
1bf50 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
1bf60 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
1bf70 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
1bf80 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
1bf90 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
1bfa0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
1bfb0 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
1bfc0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
1bfd0 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
1bfe0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
1bff0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
1c000 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
1c010 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
1c020 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
1c030 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49   bytes..**.** ^I
1c040 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
1c050 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
1c060 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1c070 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
1c080 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
1c090 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
1c0a0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1c0b0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
1c0c0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
1c0d0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
1c0e0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
1c0f0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
1c100 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1c110 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
1c120 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
1c130 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
1c140 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1c150 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
1c160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c170 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
1c180 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
1c190 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1c1a0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
1c1b0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1c1c0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1c1d0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
1c1e0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1c1f0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1c200 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1c210 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1c220 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1c230 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1c240 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
1c250 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
1c260 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
1c270 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
1c280 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
1c290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
1c2a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1c2b0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
1c2c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1c2d0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
1c2e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
1c2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
1c300 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
1c310 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
1c320 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
1c330 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1c340 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
1c350 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1c360 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1c370 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
1c380 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
1c390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c3a0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
1c3b0 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
1c3c0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
1c3d0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
1c3e0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
1c3f0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
1c400 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
1c410 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
1c420 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
1c430 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
1c440 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
1c450 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1c460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c470 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1c480 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1c490 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1c4a0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1c4b0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1c4c0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1c4d0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1c4e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1c4f0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1c500 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
1c510 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
1c520 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1c530 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
1c540 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
1c550 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
1c560 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
1c570 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
1c580 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
1c590 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
1c5a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
1c5b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1c5c0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
1c5d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
1c5e0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
1c5f0 61 69 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63  ain.  ^If the sc
1c600 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
1c610 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
1c620 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
1c630 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
1c640 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
1c650 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
1c660 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
1c670 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
1c680 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
1c690 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
1c6a0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
1c6b0 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
1c6c0 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1c6d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c6e0 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
1c6f0 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
1c700 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
1c710 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
1c720 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1c730 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
1c740 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
1c750 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
1c760 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
1c770 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
1c780 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
1c790 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
1c7a0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1c7b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1c7c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
1c7d0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
1c7e0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
1c7f0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1c800 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
1c810 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
1c820 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
1c830 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c840 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
1c850 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
1c860 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
1c870 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
1c880 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1c890 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1c8a0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1c8b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1c8c0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
1c8d0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
1c8e0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1c8f0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1c900 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1c910 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1c920 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1c930 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1c940 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1c950 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1c960 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1c970 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
1c980 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61  value of a [para
1c990 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
1c9a0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57  ameter] in the W
1c9b0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
1c9c0 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  t.** change the 
1c9d0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
1c9e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e   statement, then
1c9f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d   the statement m
1ca00 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ay be.** automat
1ca10 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1ca20 64 20 28 61 73 20 69 66 20 74 68 65 72 65 20 68  d (as if there h
1ca30 61 64 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61  ad been a schema
1ca40 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20   change) on the 
1ca50 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74  first .** [sqlit
1ca60 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
1ca70 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
1ca80 61 6e 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20  ange to the .** 
1ca90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1caa0 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
1cab0 66 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  f the [parameter
1cac0 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ]. .** </li>.** 
1cad0 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
1cae0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
1caf0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1cb00 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1cb10 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1cb20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1cb30 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1cb40 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1cb50 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1cb60 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1cb70 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1cb80 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1cb90 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1cba0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1cbb0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1cbc0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1cbd0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1cbe0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1cbf0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1cc00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1cc10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1cc20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1cc30 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1cc40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1cc50 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1cc60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1cc70 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1cc80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1cc90 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1cca0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ccb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ccc0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ccd0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1cce0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1ccf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1cd00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1cd10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1cd20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1cd30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1cd40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1cd50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1cd60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1cd70 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1cd80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1cd90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1cda0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1cdb0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1cdc0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1cdd0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1cde0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1cdf0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1ce00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1ce10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1ce20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1ce30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1ce40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1ce50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1ce60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1ce70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1ce80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1ce90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1cea0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1ceb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1cec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1ced0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1cee0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1cef0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1cf00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1cf10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1cf20 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1cf30 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1cf40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1cf50 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1cf60 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1cf70 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1cf80 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1cf90 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1cfa0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1cfb0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1cfc0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1cfd0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1cfe0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1cff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d000 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1d010 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
1d020 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
1d030 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1d040 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
1d050 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
1d060 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
1d070 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
1d080 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1d090 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
1d0a0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
1d0b0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1d0c0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1d0d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d0e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d0f0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f  e16_v2()]..*/.co
1d100 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1d110 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
1d120 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1d130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1d140 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1d150 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
1d160 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
1d170 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1d180 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
1d190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
1d1a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1d1b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
1d1c0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
1d1d0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
1d1e0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1d1f0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
1d200 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
1d210 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1d220 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
1d230 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
1d240 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
1d250 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
1d260 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
1d270 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
1d280 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
1d290 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
1d2a0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
1d2b0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
1d2c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1d2d0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
1d2e0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
1d2f0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
1d300 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
1d310 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
1d320 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1d330 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
1d340 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
1d350 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
1d360 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
1d370 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1d380 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
1d390 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
1d3a0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
1d3b0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
1d3c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
1d3d0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
1d3e0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
1d3f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1d400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
1d410 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
1d420 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
1d430 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
1d440 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
1d450 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
1d460 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
1d470 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
1d480 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1d490 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
1d4a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
1d4b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
1d4c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1d4d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
1d4e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1d4f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
1d500 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
1d510 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
1d520 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
1d530 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
1d540 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
1d550 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
1d560 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
1d570 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
1d580 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
1d590 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1d5a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
1d5b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1d5c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
1d5d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1d5e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1d5f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1d600 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1d610 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1d620 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1d630 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
1d640 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
1d650 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
1d660 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
1d670 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
1d680 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
1d690 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
1d6a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
1d6b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1d6c0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1d6d0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1d6e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d6f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1d700 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
1d710 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
1d720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d730 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
1d740 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
1d750 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
1d760 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
1d770 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
1d780 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1d790 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
1d7a0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
1d7b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
1d7c0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
1d7d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
1d7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
1d7f0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
1d800 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
1d810 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1d820 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
1d830 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
1d840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1d850 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
1d860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1d870 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
1d880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
1d890 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
1d8a0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
1d8b0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
1d8c0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
1d8d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1d8e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
1d8f0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
1d900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
1d910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d920 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
1d930 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
1d940 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1d950 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1d960 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1d970 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1d980 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1d990 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
1d9a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1d9b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
1d9c0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
1d9d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d9e0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
1d9f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1da00 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
1da10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1da20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1da30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1da40 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
1da50 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
1da60 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
1da70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1da80 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
1da90 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
1daa0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1dab0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
1dac0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
1dad0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
1dae0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
1daf0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
1db00 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
1db10 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
1db20 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
1db30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1db40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1db50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1db60 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1db70 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
1db80 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
1db90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
1dba0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
1dbb0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
1dbc0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
1dbd0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
1dbe0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1dbf0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
1dc00 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
1dc10 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1dc20 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
1dc30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1dc40 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
1dc50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dc60 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
1dc70 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
1dc80 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1dc90 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
1dca0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
1dcb0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
1dcc0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
1dcd0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1dce0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1dcf0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1dd00 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1dd10 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1dd20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1dd30 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
1dd40 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
1dd50 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
1dd60 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
1dd70 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
1dd80 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
1dd90 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20  ntifer.)^  ^The 
1dda0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
1ddb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
1ddc0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
1ddd0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
1dde0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
1ddf0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1de00 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1de10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1de20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1de30 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
1de40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1de50 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1de60 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1de70 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
1de80 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1de90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1dea0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1deb0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1dec0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ded0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
1dee0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
1def0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1df00 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
1df10 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
1df20 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
1df30 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
1df40 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1df50 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
1df60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1df70 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1df80 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
1df90 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
1dfa0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
1dfb0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
1dfc0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
1dfd0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
1dfe0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
1dff0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
1e000 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
1e010 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
1e020 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
1e030 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e040 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
1e050 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
1e060 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1e070 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1e080 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1e090 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
1e0a0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
1e0b0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
1e0c0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
1e0d0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
1e0e0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
1e0f0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
1e100 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
1e110 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
1e120 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1e130 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
1e140 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
1e150 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  meter..**.** ^(I
1e160 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
1e170 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
1e180 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
1e190 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
1e1a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
1e1b0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
1e1c0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
1e1d0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
1e1e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1e1f0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
1e200 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
1e210 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1e220 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
1e230 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1e240 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1e250 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1e260 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1e270 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1e280 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1e290 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1e2a0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  inator..**.** ^T
1e2b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1e2c0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
1e2d0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
1e2e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
1e2f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
1e300 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
1e310 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
1e320 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
1e330 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
1e340 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
1e350 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
1e360 69 74 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20  ith it. ^If the 
1e370 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
1e380 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
1e390 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
1e3a0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
1e3b0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
1e3c0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
1e3d0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
1e3e0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
1e3f0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
1e400 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
1e410 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
1e420 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
1e430 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
1e440 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
1e450 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
1e460 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
1e470 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
1e480 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
1e490 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
1e4a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1e4b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
1e4c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e4d0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1e4e0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
1e4f0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
1e500 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
1e510 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
1e520 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
1e530 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
1e540 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
1e550 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
1e560 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
1e570 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
1e580 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
1e590 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
1e5a0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
1e5b0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
1e5c0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
1e5d0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
1e5e0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
1e5f0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1e600 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
1e610 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
1e620 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
1e630 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
1e640 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1e650 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1e660 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1e670 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
1e680 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1e690 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1e6a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
1e6b0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e6c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
1e6d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e6e0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
1e6f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
1e700 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
1e710 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
1e720 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
1e730 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
1e740 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e750 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
1e760 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
1e770 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
1e780 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
1e790 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
1e7a0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
1e7b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e7c0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
1e7d0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
1e7e0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
1e7f0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
1e800 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
1e810 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
1e820 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
1e830 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
1e840 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
1e850 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
1e860 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1e870 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1e880 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e890 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
1e8a0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1e8b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1e8c0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
1e8d0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
1e8e0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
1e8f0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
1e900 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1e910 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1e920 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1e930 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
1e940 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
1e950 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
1e960 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
1e970 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1e980 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e990 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
1e9a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1e9b0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1e9c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1e9d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1e9e0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1e9f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
1ea00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ea10 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1ea20 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1ea30 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1ea40 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
1ea50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ea60 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
1ea70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
1ea80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1ea90 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
1eaa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
1eab0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
1eac0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
1ead0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
1eae0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
1eaf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1eb00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1eb10 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
1eb20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1eb30 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
1eb40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1eb50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1eb60 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
1eb70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1eb80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1eb90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1eba0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ebb0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
1ebc0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1ebd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
1ebe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ebf0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
1ec00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
1ec10 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
1ec20 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1ec30 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
1ec40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1ec50 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
1ec60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
1ec70 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
1ec80 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
1ec90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1eca0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
1ecb0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
1ecc0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
1ecd0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
1ece0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
1ecf0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
1ed00 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
1ed10 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
1ed20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
1ed30 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
1ed40 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
1ed50 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
1ed60 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
1ed70 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
1ed80 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
1ed90 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1eda0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
1edb0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
1edc0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
1edd0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1ede0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1edf0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
1ee00 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
1ee10 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1ee20 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1ee30 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
1ee40 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
1ee50 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
1ee60 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
1ee70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1ee80 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1ee90 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1eea0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1eeb0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
1eec0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1eed0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1eee0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1eef0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1ef00 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
1ef10 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1ef20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1ef30 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
1ef40 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
1ef50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1ef60 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
1ef70 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
1ef80 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
1ef90 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
1efa0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
1efb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1efc0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
1efd0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
1efe0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1eff0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1f000 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1f010 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1f020 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1f030 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1f040 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1f050 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1f060 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1f070 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1f080 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1f090 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1f0a0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1f0b0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1f0c0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
1f0d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1f0e0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
1f0f0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
1f100 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
1f110 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
1f120 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
1f130 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
1f140 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
1f150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1f160 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
1f170 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1f180 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
1f190 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
1f1a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1f1b0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
1f1c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1f1d0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
1f1e0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
1f1f0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
1f200 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
1f210 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
1f220 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
1f230 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
1f240 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
1f250 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
1f260 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
1f270 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f280 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1f290 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1f2a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1f2b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f2c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1f2d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1f2e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f2f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1f300 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f310 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1f320 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
1f330 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1f340 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1f350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f370 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1f380 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1f390 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
1f3a0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
1f3b0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
1f3c0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
1f3d0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
1f3e0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
1f3f0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
1f400 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
1f410 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
1f420 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1f430 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1f440 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
1f450 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
1f460 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
1f470 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
1f480 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
1f490 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
1f4a0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
1f4b0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
1f4c0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1f4d0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
1f4e0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
1f4f0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
1f500 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1f510 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
1f520 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1f530 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1f540 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1f550 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f560 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
1f570 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1f580 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1f590 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
1f5a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f5b0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
1f5c0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
1f5d0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
1f5e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1f5f0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
1f600 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
1f610 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
1f620 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
1f630 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
1f640 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
1f650 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
1f660 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
1f670 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1f680 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
1f690 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f6a0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
1f6b0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
1f6c0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
1f6d0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
1f6e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f6f0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
1f700 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1f710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f720 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
1f730 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
1f740 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
1f750 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1f760 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1f770 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
1f780 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
1f790 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1f7a0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1f7b0 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
1f7c0 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
1f7d0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
1f7e0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
1f7f0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
1f800 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f  an [UPDATE])..*/
1f810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
1f820 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
1f830 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1f840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f850 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
1f860 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
1f870 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1f880 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
1f890 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
1f8a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
1f8b0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
1f8c0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1f8d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f8e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1f8f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
1f900 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f910 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f920 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1f930 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
1f940 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
1f950 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
1f960 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1f970 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1f980 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1f990 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
1f9a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1f9b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f9c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
1f9d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1f9e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1f9f0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
1fa00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1fa10 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
1fa20 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
1fa30 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
1fa40 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
1fa50 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1fa60 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
1fa70 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
1fa80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1fa90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
1faa0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1fab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1fac0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
1fad0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
1fae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1faf0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
1fb00 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
1fb10 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1fb20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
1fb30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
1fb40 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
1fb50 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
1fb60 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
1fb70 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
1fb80 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
1fb90 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
1fba0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
1fbb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
1fbc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1fbd0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
1fbe0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
1fbf0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1fc00 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
1fc10 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
1fc20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
1fc30 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
1fc40 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
1fc50 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
1fc60 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
1fc70 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
1fc80 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
1fc90 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
1fca0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
1fcb0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
1fcc0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1fcd0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
1fce0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1fcf0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
1fd00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1fd10 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1fd20 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
1fd30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fd40 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
1fd50 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
1fd60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1fd70 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1fd80 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1fd90 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
1fda0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
1fdb0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1fdc0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
1fdd0 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
1fde0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
1fdf0 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
1fe00 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
1fe10 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1fe20 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
1fe30 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
1fe40 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
1fe50 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
1fe60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
1fe70 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
1fe80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
1fe90 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1fea0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
1feb0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1fec0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
1fed0 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
1fee0 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
1fef0 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
1ff00 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
1ff10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1ff20 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1ff30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ff40 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
1ff50 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
1ff60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1ff70 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
1ff80 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
1ff90 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
1ffa0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
1ffb0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
1ffc0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
1ffd0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
1ffe0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
1fff0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
20000 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
20010 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
20020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20030 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
20040 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
20050 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
20060 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
20070 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
20080 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
20090 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
200a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
200b0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
200c0 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
200d0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
200e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
200f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
20100 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
20110 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
20120 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
20130 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
20140 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
20150 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
20160 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
20170 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
20180 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
20190 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
201a0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
201b0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
201c0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
201d0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
201e0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
201f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
20200 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
20210 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
20220 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
20230 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
20240 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
20250 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
20260 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
20270 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
20280 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
20290 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
202a0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
202b0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
202c0 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
202d0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
202e0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
202f0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
20300 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
20310 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
20320 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
20330 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
20340 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
20350 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
20360 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
20370 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
20380 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
20390 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
203a0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
203b0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
203c0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
203d0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
203e0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
203f0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
20400 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
20410 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
20420 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
20430 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
20440 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
20450 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
20460 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
20470 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
20480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20490 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
204a0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
204b0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
204c0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
204d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
204e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
204f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
20500 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
20510 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
20520 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
20530 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20540 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
20550 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20560 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
20580 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
20590 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
205a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
205b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
205c0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
205d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
205e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
205f0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
20600 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20610 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
20620 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
20630 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
20640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20650 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
20670 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
20680 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
20690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
206a0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
206b0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
206c0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
206d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
206e0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
206f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
20700 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
20710 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
20720 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
20730 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
20740 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
20750 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
20760 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
20770 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
20780 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
20790 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
207a0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
207b0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
207c0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
207d0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
207e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
207f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
20800 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
20810 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
20820 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
20830 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
20840 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
20850 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
20860 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
20870 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
20880 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
20890 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
208a0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
208b0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
208c0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
208d0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
208e0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
208f0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
20900 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
20910 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
20920 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
20930 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
20940 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
20950 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
20960 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
20970 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
20980 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
20990 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
209a0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
209b0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
209c0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
209d0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
209e0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
209f0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
20a00 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
20a10 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
20a20 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
20a30 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
20a40 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
20a50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
20a60 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
20a70 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
20a80 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
20a90 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
20aa0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
20ab0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
20ac0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
20ad0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
20ae0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
20af0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
20b00 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
20b10 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
20b20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20b30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20b40 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
20b50 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
20b60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
20b70 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
20b80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20b90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20ba0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
20bb0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
20bc0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
20bd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
20be0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
20bf0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
20c00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20c10 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
20c20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20c30 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
20c40 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
20c50 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
20c60 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
20c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20c80 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
20c90 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
20ca0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
20cb0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
20cc0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
20cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
20ce0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
20cf0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
20d00 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
20d10 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
20d20 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
20d30 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
20d40 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
20d50 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
20d60 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
20d70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20d80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20d90 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
20da0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
20db0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
20dc0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
20dd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
20de0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
20df0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
20e00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
20e10 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
20e20 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
20e30 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
20e40 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
20e50 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
20e60 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
20e70 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
20e80 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
20e90 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
20ea0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
20eb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
20ec0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
20ed0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
20ee0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
20ef0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
20f00 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
20f10 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
20f20 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
20f30 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
20f40 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
20f50 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
20f60 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
20f70 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
20f80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
20f90 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
20fa0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
20fb0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
20fc0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
20fd0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
20fe0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
20ff0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
21000 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
21010 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
21020 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
21030 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
21040 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
21050 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
21060 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
21070 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
21080 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
21090 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
210a0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
210b0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
210c0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
210d0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
210e0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
210f0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
21100 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
21110 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
21120 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
21130 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
21140 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
21150 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
21160 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
21170 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
21180 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
21190 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
211a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
211b0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
211c0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
211d0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
211e0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
211f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
21200 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21210 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
21220 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
21230 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
21240 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
21250 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
21260 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
21270 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
21280 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
21290 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
212a0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
212b0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
212c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
212d0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
212e0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
212f0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
21300 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
21310 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
21320 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
21330 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
21340 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
21350 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
21360 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
21370 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
21380 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
21390 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
213a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
213b0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
213c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
213d0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
213e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
213f0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
21400 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
21410 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
21420 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
21430 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
21440 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
21450 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
21460 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
21470 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
21480 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
21490 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
214a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
214b0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
214c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
214d0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
214e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
214f0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
21500 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
21510 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
21520 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
21530 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
21540 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
21550 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
21560 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
21570 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
21580 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
21590 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
215a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
215b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
215c0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
215d0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
215e0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
215f0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
21600 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
21610 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
21620 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
21630 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
21640 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
21650 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
21660 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
21670 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
21680 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
21690 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
216a0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
216b0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
216c0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
216d0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
216e0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
216f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
21700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
21710 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
21720 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
21730 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
21740 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
21750 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
21760 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
21770 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
21780 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
21790 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
217a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
217b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
217c0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
217d0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
217e0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
217f0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
21800 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
21810 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21820 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
21830 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
21840 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
21850 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
21860 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
21870 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21880 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
21890 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
218a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
218b0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
218c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
218d0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
218e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
218f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
21900 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
21910 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
21920 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
21930 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
21940 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
21950 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
21960 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
21970 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
21980 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
21990 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
219a0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
219b0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
219c0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
219d0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
219e0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
219f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
21a00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
21a10 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
21a20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21a30 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74  _data_count(P) t
21a40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
21a50 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f  umns in the.** o
21a60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
21a70 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
21a80 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69  atement] P..*/.i
21a90 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
21aa0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
21ab0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
21ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
21ad0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
21ae0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
21af0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
21b00 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
21b10 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
21b20 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
21b30 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
21b40 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
21b50 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
21b60 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
21b70 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
21b80 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
21b90 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
21ba0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
21bb0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
21bc0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
21bd0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
21be0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
21bf0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
21c00 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
21c10 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
21c20 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
21c30 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
21c40 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
21c50 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
21c60 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
21c70 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
21c80 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
21c90 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
21ca0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
21cb0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
21cc0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
21cd0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
21ce0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
21cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
21d00 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
21d10 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
21d20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
21d30 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
21d40 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
21d50 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
21d60 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
21d70 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
21d80 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
21d90 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
21da0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
21db0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
21dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21dd0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
21de0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
21df0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
21e00 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
21e10 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
21e20 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
21e30 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
21e40 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
21e50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
21e60 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
21e70 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
21e80 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
21e90 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
21ea0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
21eb0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
21ec0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
21ed0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
21ee0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
21ef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21f00 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
21f10 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
21f20 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
21f30 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
21f40 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
21f50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21f60 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
21f70 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
21f80 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
21f90 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
21fa0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
21fb0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
21fc0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
21fd0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
21fe0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
21ff0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
22000 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
22010 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
22020 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
22030 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
22040 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
22050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
22060 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
22070 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
22080 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
22090 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
220a0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
220b0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
220c0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
220d0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
220e0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
220f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
22100 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
22110 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
22120 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22130 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
22140 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
22150 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
22160 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
22170 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
22180 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
22190 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
221a0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
221b0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
221c0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
221d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
221e0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
221f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
22200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
22210 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
22220 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
22230 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
22240 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
22250 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22260 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
22270 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
22280 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
22290 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
222a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
222b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
222c0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
222d0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
222e0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
222f0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
22300 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
22310 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
22320 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22330 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
22340 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22350 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
22360 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
22370 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
22380 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
22390 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
223a0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
223b0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
223c0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
223d0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
223e0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
223f0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
22400 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
22410 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
22420 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
22430 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
22440 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
22450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22460 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
22470 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
22480 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
22490 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
224a0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
224b0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
224c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
224d0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
224e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
224f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
22500 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
22510 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
22520 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
22530 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
22540 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
22550 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
22560 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
22570 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
22580 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
22590 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
225a0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
225b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
225c0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
225d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
225e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
225f0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
22600 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
22610 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
22620 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
22630 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
22640 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
22650 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
22660 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
22670 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
22680 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
22690 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
226a0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
226b0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
226c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
226d0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
226e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
226f0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
22700 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
22710 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
22720 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
22730 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
22740 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54  at string..** ^T
22750 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
22760 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
22770 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
22780 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
22790 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
227a0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
227b0 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
227c0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
227d0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
227e0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
227f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
22800 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
22810 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
22820 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
22830 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
22840 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
22850 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
22860 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
22870 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
22880 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o terminated.  ^
22890 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
228a0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
228b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
228c0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
228d0 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69   BLOB is an arbi
228e0 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
228f0 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
22900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
22910 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22920 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
22930 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
22940 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
22950 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22960 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
22970 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
22980 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
22990 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
229a0 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54   of UTF-8..** ^T
229b0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
229c0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
229d0 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
229e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
229f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
22a00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22a10 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
22a20 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
22a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
22a40 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
22a50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22a60 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
22a70 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
22a80 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
22a90 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
22aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
22ab0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
22ac0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
22ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
22ae0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
22af0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
22b00 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
22b10 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
22b20 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
22b30 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
22b40 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
22b50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
22b60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
22b70 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
22b80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22b90 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
22ba0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
22bb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
22bc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
22bd0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
22be0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
22bf0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
22c00 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
22c10 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
22c20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
22c30 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
22c40 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
22c50 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
22c60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
22c70 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
22c80 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
22c90 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
22ca0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
22cb0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
22cc0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
22cd0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
22ce0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
22cf0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
22d00 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
22d10 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
22d20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
22d30 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
22d40 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
22d50 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
22d60 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
22d70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
22d80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
22d90 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
22da0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
22db0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
22dc0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
22dd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
22de0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
22df0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
22e00 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
22e10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
22e20 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
22e30 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
22e40 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
22e50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
22e60 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
22e70 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
22e80 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
22e90 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
22ea0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
22eb0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
22ec0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
22ed0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
22ee0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
22ef0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
22f00 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
22f10 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
22f20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
22f30 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
22f40 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
22f50 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
22f60 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
22f70 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
22f80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
22f90 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
22fa0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
22fb0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
22fc0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
22fd0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
22fe0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
22ff0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
23000 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
23010 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
23020 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23030 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
23040 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
23050 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
23060 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
23070 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
23080 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
23090 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
230a0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
230b0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
230c0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
230d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
230e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
230f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
23100 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
23110 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
23120 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
23130 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
23140 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
23150 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
23160 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
23170 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
23180 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
23190 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
231a0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
231b0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
231c0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
231d0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
231e0 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
231f0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
23200 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
23210 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
23220 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
23230 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
23240 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
23250 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
23260 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
23270 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
23280 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
23290 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
232a0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
232b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
232c0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
232d0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
232e0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
232f0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
23300 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
23310 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
23320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23330 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
23340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23350 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
23360 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28  validated..** ^(
23370 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
23380 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
23390 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
233a0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
233b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
233c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
233d0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
233e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
233f0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
23400 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
23410 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
23420 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
23430 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
23440 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
23450 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
23460 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
23470 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
23480 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
23490 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
234a0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
234b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
234c0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
234d0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
234e0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
234f0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
23500 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
23510 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
23520 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
23530 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
23540 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
23550 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
23560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23570 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
23580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23590 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
235a0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
235b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
235c0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
235d0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  /li>.** </ul>)^.
235e0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
235f0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
23600 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
23610 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
23620 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
23630 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
23640 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
23650 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
23660 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
23670 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
23680 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
23690 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
236a0 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
236b0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
236c0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
236d0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
236e0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
236f0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
23700 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
23710 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
23720 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
23730 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
23740 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
23750 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
23760 20 5e 28 54 68 65 20 73 61 66 65 73 74 20 61 6e   ^(The safest an
23770 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
23780 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
23790 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
237a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
237b0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
237c0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
237d0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
237e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
237f0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
23800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23810 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
23820 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
23830 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
23840 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23850 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
23860 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
23870 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23880 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
23890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
238a0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
238b0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  ul>)^.**.** In o
238c0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
238d0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
238e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
238f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
23900 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
23910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23920 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
23930 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
23940 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
23950 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
23960 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
23970 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23980 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
23990 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
239a0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
239b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
239c0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
239d0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
239e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
239f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23a00 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
23a10 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
23a20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23a30 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
23a40 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23a50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23a60 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
23a70 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
23a80 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
23a90 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
23aa0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
23ab0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
23ac0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
23ad0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
23ae0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
23af0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23b00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
23b10 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
23b20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23b30 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
23b40 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
23b50 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
23b60 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
23b70 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
23b80 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
23b90 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
23ba0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
23bb0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
23bc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
23bd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23be0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
23bf0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
23c00 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
23c10 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
23c20 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
23c30 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
23c40 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
23c50 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
23c60 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
23c70 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
23c80 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
23c90 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
23ca0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
23cb0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
23cc0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
23cd0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
23ce0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
23cf0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
23d00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
23d10 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
23d20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
23d30 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
23d40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23d50 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
23d60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
23d70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
23d80 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
23d90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23da0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
23db0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
23dc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23dd0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
23de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
23df0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
23e00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
23e10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
23e20 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
23e30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
23e40 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
23e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
23e60 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
23e70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
23e80 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
23e90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23ea0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
23eb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
23ec0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23ee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23ef0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
23f00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
23f10 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
23f20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
23f30 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
23f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
23f50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23f60 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
23f70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
23f80 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
23f90 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
23fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23fb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
23fc0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
23fd0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
23fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23ff0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74  ]..** ^If the st
24000 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
24010 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
24020 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
24030 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
24040 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
24050 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65  eturned. ^If exe
24060 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
24070 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
24080 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72  hen an.** [error
24090 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
240a0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
240b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
240c0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
240d0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
240e0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
240f0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
24100 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
24110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24120 20 20 5e 49 66 20 74 68 65 20 76 69 72 74 75 61    ^If the virtua
24130 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
24140 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  t.** completed e
24150 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
24160 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
24170 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
24180 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
24190 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
241a0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
241b0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
241c0 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74  ]..** ^Incomplet
241d0 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
241e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
241f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
24200 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
24210 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
24220 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
24230 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
24240 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
24250 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
24260 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  T]..*/.int sqlit
24270 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
24280 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
242a0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
242b0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
242c0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
242d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
242e0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
242f0 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
24300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24310 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
24320 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
24330 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
24340 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
24350 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
24360 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
24370 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
24380 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
24390 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
243a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
243b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
243c0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
243d0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
243e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
243f0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
24400 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
24410 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
24420 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
24430 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
24440 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
24450 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
24460 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
24470 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
24480 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
24490 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
244a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
244b0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
244c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
244d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
244e0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
244f0 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
24500 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
24510 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
24520 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
24530 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
24540 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
24550 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
24560 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
24570 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
24580 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
24590 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
245a0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
245b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
245c0 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
245d0 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
245e0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
245f0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
24600 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
24610 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
24620 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
24630 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
24640 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
24650 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
24660 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
24670 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
24680 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
24690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
246a0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
246b0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
246c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
246d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
246e0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
246f0 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
24700 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
24710 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
24720 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
24730 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
24740 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
24750 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
24760 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
24770 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
24780 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
24790 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66  .** ^These two f
247a0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
247b0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
247c0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
247d0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
247e0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
247f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
24800 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
24810 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
24820 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
24830 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
24840 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
24850 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
24860 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
24870 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
24880 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
24890 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
248a0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
248b0 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
248c0 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
248d0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
248e0 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
248f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
24900 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
24910 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24920 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
24930 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
24940 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
24950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24960 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
24970 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
24980 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
24990 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
249a0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
249b0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
249c0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
249d0 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
249e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
249f0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
24a00 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
24a10 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
24a20 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
24a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
24a40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
24a50 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24a60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
24a70 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
24a80 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
24a90 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
24aa0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
24ab0 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
24ac0 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
24ad0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
24ae0 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
24af0 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
24b00 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
24b10 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
24b20 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70  rs.  ^Any attemp
24b30 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
24b40 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
24b50 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
24b60 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
24b70 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
24b80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24b90 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
24ba0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
24bb0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
24bc0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
24bd0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
24be0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
24bf0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
24c00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
24c10 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
24c20 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
24c30 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
24c40 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
24c50 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
24c60 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
24c70 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
24c80 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
24c90 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
24ca0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
24cb0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
24cc0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
24cd0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
24ce0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
24cf0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
24d00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24d10 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
24d20 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
24d30 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
24d40 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
24d50 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
24d60 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
24d70 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
24d80 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
24d90 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
24da0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
24db0 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
24dc0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
24dd0 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
24de0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
24df0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
24e00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
24e10 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
24e20 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
24e30 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
24e40 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
24e50 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
24e60 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
24e70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
24e80 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
24e90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
24ea0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
24eb0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
24ec0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
24ed0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
24ee0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
24ef0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
24f00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24f10 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
24f20 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
24f30 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
24f40 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
24f50 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
24f60 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
24f70 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
24f80 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
24f90 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
24fa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24fb0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
24fc0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
24fd0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
24fe0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
24ff0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
25000 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
25010 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
25020 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
25030 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
25040 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
25050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
25060 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
25070 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
25080 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
25090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
250a0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
250b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
250c0 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
250d0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
250e0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
250f0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
25100 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
25110 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
25120 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
25130 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25140 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
25150 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
25160 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
25170 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
25180 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
25190 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
251a0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
251b0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
251c0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
251d0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
251e0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
251f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
25200 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
25210 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
25220 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
25230 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
25240 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
25250 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
25260 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
25270 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
25280 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
25290 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
252a0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
252b0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
252c0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
252d0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
252e0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
252f0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
25300 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
25310 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
25320 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
25330 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
25340 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
25350 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
25360 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
25370 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
25380 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
25390 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
253a0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
253b0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
253c0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
253d0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
253e0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
253f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
25400 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
25410 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
25420 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
25430 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
25440 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
25450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25460 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
25470 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
25480 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
25490 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
254a0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
254b0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
254c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
254d0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
254e0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
254f0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
25500 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
25510 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
25520 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
25530 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
25540 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
25550 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
25560 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
25570 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
25580 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
25590 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
255a0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
255b0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
255c0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
255d0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
255e0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
255f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
25600 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
25610 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 70  ** ^The first ap
25620 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25630 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  d function with 
25640 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65  a given name ove
25650 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75  rrides all.** bu
25660 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
25670 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   in the same [da
25680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25690 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  n] with the same
256a0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65   name..** ^Subse
256b0 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  quent applicatio
256c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
256d0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
256e0 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69  name only overri
256f0 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70  de .** prior app
25700 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25710 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
25720 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74  are an exact mat
25730 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75  ch for the.** nu
25740 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
25750 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64  rs and preferred
25760 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
25770 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
25780 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25790 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
257a0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
257b0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
257c0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
257d0 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
257e0 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
257f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25800 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
25810 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
25820 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
25830 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
25840 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
25850 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
25860 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25870 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
25880 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
25890 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
258a0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
258b0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
258c0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
258d0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
258e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
258f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
25900 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
25910 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25920 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25930 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
25940 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
25950 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
25960 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
25970 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
25980 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
25990 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
259a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
259b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
259c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
259d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
259e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
259f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
25a00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
25a10 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
25a20 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
25a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
25a40 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
25a50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
25a60 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t*).);../*.** CA
25a70 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
25a80 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
25a90 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
25aa0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
25ab0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
25ac0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
25ad0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
25ae0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
25af0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
25b00 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
25b10 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
25b20 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
25b30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
25b40 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
25b50 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
25b60 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
25b70 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
25b80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
25b90 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
25ba0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
25bb0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
25bc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25bd0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
25be0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
25bf0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
25c00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
25c10 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
25c20 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
25c30 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
25c40 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
25c50 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
25c60 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
25c70 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
25c80 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
25c90 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
25ca0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
25cb0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
25cc0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
25cd0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
25ce0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
25cf0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
25d00 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
25d10 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
25d20 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
25d30 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
25d40 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
25d50 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
25d60 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
25d70 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
25d80 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
25d90 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
25da0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
25db0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
25dc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
25dd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
25de0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
25df0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
25e00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
25e10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
25e20 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
25e30 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
25e40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
25e50 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
25e60 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
25e70 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
25e80 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
25e90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
25ea0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
25eb0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
25ec0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
25ed0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
25ee0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
25ef0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
25f00 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
25f10 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
25f20 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
25f30 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
25f40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
25f50 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
25f60 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
25f70 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
25f80 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
25f90 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
25fa0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
25fb0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
25fc0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
25fd0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
25fe0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
25ff0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
26000 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
26010 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
26020 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
26030 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
26040 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
26050 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
26060 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
26070 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
26080 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
26090 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
260a0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
260b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
260c0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
260d0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
260e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
260f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
26100 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
26110 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
26120 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
26130 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
26140 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
26150 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
26160 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
26170 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
26180 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
26190 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
261a0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
261b0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
261c0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
261d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
261e0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
261f0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
26200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
26210 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
26220 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
26230 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
26240 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26250 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
26260 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
26270 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
26280 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
26290 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
262a0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
262b0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
262c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
262d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
262e0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
262f0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
26300 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
26310 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
26320 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
26330 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
26340 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
26350 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26360 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
26370 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
26380 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
26390 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
263a0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
263b0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
263c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
263d0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
263e0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
263f0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
26400 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
26410 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
26420 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
26430 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
26440 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26450 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
26460 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
26470 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
26480 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
26490 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
264a0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
264b0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
264c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
264d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
264e0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
264f0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
26500 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
26510 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
26520 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
26530 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
26540 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
26550 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
26560 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
26570 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
26580 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
26590 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
265a0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
265b0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
265c0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
265d0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
265e0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
265f0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
26600 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
26610 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
26620 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
26630 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
26640 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
26650 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
26660 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
26670 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
26680 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
26690 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
266a0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
266b0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
266c0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
266d0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
266e0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
266f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
26700 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
26710 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
26720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
26730 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
26740 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
26750 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
26760 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
26770 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
26780 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
26790 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
267a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
267b0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
267c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
267d0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
267e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
267f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
26800 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
26810 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
26820 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
26830 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
26840 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
26850 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
26860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
26870 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
26880 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
26890 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
268a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
268b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
268c0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
268d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
268e0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
268f0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
26900 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
26910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
26920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26930 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
26940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
26950 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
26960 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
26970 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
26980 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
26990 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
269a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
269b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
269c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
269d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
269e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
269f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
26a00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
26a10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26a20 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
26a30 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26a40 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
26a50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
26a60 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
26a70 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
26a80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
26a90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26aa0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
26ab0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
26ac0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
26ad0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
26ae0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
26af0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
26b00 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
26b10 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
26b20 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
26b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26b40 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
26b50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26b60 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
26b70 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
26b80 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
26b90 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
26ba0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
26bb0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
26bc0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
26bd0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
26be0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
26bf0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
26c00 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
26c10 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
26c20 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
26c30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26c40 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
26c50 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
26c60 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
26c70 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
26c80 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
26c90 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
26ca0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26cb0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
26cc0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
26cd0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
26ce0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
26cf0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
26d00 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
26d10 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
26d20 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
26d30 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
26d40 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
26d50 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
26d60 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
26d70 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
26d80 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
26d90 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
26da0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
26db0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
26dc0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
26dd0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
26de0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
26df0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26e00 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
26e10 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
26e20 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
26e30 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
26e40 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
26e50 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
26e60 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
26e70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
26e80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
26e90 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
26ea0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
26eb0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
26ec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
26ed0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
26ee0 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
26ef0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
26f00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
26f10 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
26f20 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
26f30 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
26f40 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
26f50 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
26f60 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
26f70 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
26f80 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
26f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
26fa0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
26fb0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
26fc0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
26fd0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
26fe0 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
26ff0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
27000 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
27010 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
27020 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
27030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
27040 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
27050 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27060 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
27070 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
27080 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
27090 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
270a0 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
270b0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
270c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
270d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
270e0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
270f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27100 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
27110 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
27120 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
27130 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
27140 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
27150 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
27160 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
27170 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
27180 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
27190 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
271a0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
271b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
271c0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
271d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
271e0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
271f0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
27200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27210 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
27220 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
27230 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
27240 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
27250 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
27260 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
27270 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
27280 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
27290 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
272a0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
272b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
272c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
272d0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
272e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
272f0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
27300 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
27310 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
27320 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
27330 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
27340 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
27350 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
27360 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
27370 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
27380 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
27390 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
273a0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
273b0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
273c0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
273d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
273e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
273f0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
27400 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
27410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27420 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
27430 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
27440 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
27450 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
27460 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
27470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
27480 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
27490 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
274a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
274b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
274c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
274d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
274e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
274f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
27500 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
27510 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
27520 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
27530 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
27540 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
27550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
27560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27570 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
27580 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
27590 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
275a0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
275b0 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
275c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
275d0 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
275e0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
275f0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
27600 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
27610 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
27620 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
27630 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
27640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
27650 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
27660 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
27670 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
27680 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
27690 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
276a0 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
276b0 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
276c0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
276d0 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
276e0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
276f0 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
27700 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
27710 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
27720 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
27730 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
27740 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
27750 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
27760 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
27770 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
27780 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
27790 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
277a0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
277b0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
277c0 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
277d0 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
277e0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
277f0 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
27800 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
27810 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
27820 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27830 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
27840 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
27850 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
27860 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
27870 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
27880 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
27890 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
278a0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
278b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
278c0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
278d0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
278e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
278f0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
27900 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27910 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
27920 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
27930 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
27940 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
27950 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
27960 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
27970 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
27980 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
27990 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
279a0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
279b0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
279c0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
279d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
279e0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
279f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
27a00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
27a10 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
27a20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
27a30 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
27a40 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
27a50 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
27a60 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
27a70 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
27a80 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
27a90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27aa0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
27ab0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
27ac0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27ad0 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
27ae0 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
27af0 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
27b00 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
27b10 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
27b20 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
27b30 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
27b40 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
27b50 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
27b60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
27b70 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27b80 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
27b90 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
27ba0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
27bb0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
27bc0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
27bd0 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
27be0 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
27bf0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
27c00 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
27c10 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
27c20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
27c30 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
27c40 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
27c50 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
27c60 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
27c70 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
27c80 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
27c90 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
27ca0 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
27cb0 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
27cc0 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
27cd0 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
27ce0 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
27cf0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
27d00 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
27d10 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
27d20 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
27d30 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
27d40 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
27d50 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
27d60 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
27d70 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
27d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27d90 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
27da0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
27db0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
27dc0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
27dd0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27de0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
27df0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27e10 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
27e20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
27e30 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
27e40 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
27e50 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
27e60 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
27e70 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
27e80 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
27e90 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
27ea0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
27eb0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
27ec0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
27ed0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
27ee0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
27ef0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
27f00 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
27f10 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
27f20 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
27f30 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
27f40 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
27f50 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
27f60 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
27f70 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
27f80 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
27f90 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
27fa0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
27fb0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
27fc0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
27fd0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
27fe0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
27ff0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
28000 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
28010 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
28020 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
28030 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
28040 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
28050 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
28060 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
28070 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
28080 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
28090 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
280a0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
280b0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
280c0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
280d0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
280e0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
280f0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
28100 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
28110 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
28120 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
28130 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
28140 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
28150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28160 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
28170 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
28180 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
28190 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
281a0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
281b0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
281c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
281d0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
281e0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
281f0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
28200 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
28210 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
28220 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
28230 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
28240 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28250 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28260 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28270 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
28280 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
28290 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
282a0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
282b0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
282c0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
282d0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
282e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
282f0 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
28300 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
28310 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
28320 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
28330 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
28340 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
28350 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
28360 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
28370 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
28380 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28390 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
283a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
283b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
283c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
283d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
283e0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
283f0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
28400 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
28410 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
28420 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
28430 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
28440 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
28450 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
28460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28470 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
28480 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
28490 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
284a0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
284b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
284c0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
284d0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
284e0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
284f0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
28500 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
28510 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
28520 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
28530 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28540 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
28550 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
28560 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
28570 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
28580 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
28590 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
285a0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
285b0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
285c0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
285d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
285e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
285f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
28600 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28610 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
28620 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
28630 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
28640 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
28650 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
28660 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
28670 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
28680 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
28690 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
286a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
286b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
286c0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
286d0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
286e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
286f0 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
28700 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
28710 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
28720 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
28730 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
28740 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
28750 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
28760 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
28770 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
28780 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
28790 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
287a0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
287b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
287c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
287d0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
287e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
287f0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
28800 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
28810 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
28820 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
28830 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
28840 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
28850 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
28860 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
28870 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28880 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
28890 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
288a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
288b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
288c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
288d0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
288e0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
288f0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
28900 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
28910 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28920 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
28930 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28940 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
28950 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
28960 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
28970 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
28980 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
28990 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
289a0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
289b0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
289c0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
289d0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
289e0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
289f0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
28a00 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
28a10 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
28a20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
28a30 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
28a40 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
28a50 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
28a60 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
28a70 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
28a80 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
28a90 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
28aa0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
28ab0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
28ac0 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
28ad0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
28ae0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28af0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
28b00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
28b10 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
28b20 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
28b30 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
28b40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28b50 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
28b60 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
28b70 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
28b80 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
28b90 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
28ba0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
28bb0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
28bc0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
28bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
28be0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
28bf0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
28c00 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
28c10 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
28c20 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
28c30 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
28c40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28c50 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
28c60 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
28c70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
28c80 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
28c90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28ca0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
28cb0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
28cc0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
28cd0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
28ce0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
28cf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28d00 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
28d10 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
28d20 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
28d30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28d40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28d50 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
28d60 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
28d70 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
28d80 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
28d90 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
28da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
28db0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
28dc0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
28dd0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
28de0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28df0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28e00 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
28e10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28e20 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
28e30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
28e40 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
28e50 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
28e60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
28e70 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
28e80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
28e90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
28ea0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
28eb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28ec0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
28ed0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
28ee0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
28ef0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
28f00 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
28f10 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
28f20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
28f30 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
28f40 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
28f50 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
28f60 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
28f70 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
28f80 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
28f90 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
28fa0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
28fb0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
28fc0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
28fd0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
28fe0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
28ff0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29000 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
29010 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29020 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
29030 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
29040 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
29050 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
29060 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
29070 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
29080 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
29090 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
290a0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
290b0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
290c0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
290d0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
290e0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
290f0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
29100 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
29110 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
29120 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
29130 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29140 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
29150 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
29160 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29170 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29180 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29190 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
291a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
291b0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
291c0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
291d0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
291e0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
291f0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
29200 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
29210 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
29220 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
29230 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
29240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
29250 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29270 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29280 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
29290 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
292a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
292b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
292c0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
292d0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
292e0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
292f0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
29300 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
29310 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
29320 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
29330 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
29340 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
29350 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
29360 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
29370 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
29380 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
29390 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
293a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
293b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
293c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
293d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
293e0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
293f0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
29400 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
29410 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
29420 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
29430 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
29440 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
29450 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
29460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
29470 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
29480 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
29490 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
294a0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
294b0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
294c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
294d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
294e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
294f0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
29500 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29510 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
29520 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
29530 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
29540 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
29550 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
29560 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
29570 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
29580 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
29590 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
295a0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
295b0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
295c0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
295d0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
295e0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
295f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29600 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
29610 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
29620 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29630 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29640 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
29650 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
29660 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29670 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29680 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
29690 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
296a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
296b0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
296c0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
296d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
296e0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
296f0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
29700 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
29710 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
29720 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
29730 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
29740 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29750 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
29760 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
29770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
29780 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
29790 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
297a0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
297b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
297c0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
297d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
297e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
297f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
29800 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
29810 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
29820 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
29830 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
29840 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
29850 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
29860 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
29870 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
29880 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
29890 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
298a0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
298b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
298c0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
298d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
298e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
298f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
29900 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
29910 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
29920 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
29930 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
29940 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
29950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29960 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
29970 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
29980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29990 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
299a0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
299b0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
299c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
299d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
299e0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
299f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
29a00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29a10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
29a20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
29a30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29a40 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
29a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29a60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
29a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
29a80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29a90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
29aa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29ab0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29ac0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
29ad0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29ae0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
29af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29b00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29b10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
29b20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
29b30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
29b40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29b60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29b70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
29b80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29b90 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
29ba0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
29bb0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
29bc0 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68  quences.**.** Th
29bd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
29be0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
29bf0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
29c00 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
29c10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29c20 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
29c30 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
29c40 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
29c50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
29c60 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
29c70 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
29c80 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
29c90 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
29ca0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29cb0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
29cc0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29cd0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
29ce0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
29cf0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
29d00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
29d10 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a   ^In all cases.*
29d20 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
29d30 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
29d40 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
29d50 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
29d60 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
29d70 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  may be one of th
29d80 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
29d90 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53  ITE_UTF8],.** [S
29da0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
29db0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
29dc0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
29dd0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
29de0 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
29df0 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
29e00 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
29e10 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
29e20 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
29e30 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
29e40 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d  -endian, or UTF-
29e50 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72  16 big-endian, r
29e60 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68  espectively. ^Th
29e70 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
29e80 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
29e90 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
29ea0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
29eb0 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a  t the routine.**
29ec0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
29ed0 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73  s to be UTF-16 s
29ee0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61  trings in the na
29ef0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
29f00 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   or the.** argum
29f10 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49  ent can be [SQLI
29f20 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
29f30 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20  ] if the.** the 
29f40 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
29f50 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62  pointers to 16-b
29f60 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20  it word aligned 
29f70 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54  strings.** of UT
29f80 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
29f90 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
29fa0 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
29fb0 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
29fc0 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
29fd0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
29fe0 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
29ff0 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ent.  ^If it is 
2a000 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68  NULL, this is th
2a010 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69  e same as deleti
2a020 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ng the collation
2a030 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f  .** sequence (so
2a040 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
2a050 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d  not call it anym
2a060 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74  ore)..** ^Each t
2a070 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
2a080 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
2a090 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
2a0a0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
2a0b0 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
2a0c0 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
2a0d0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
2a0e0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
2a0f0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
2a100 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a110 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
2a120 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a130 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
2a140 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e  ** ^The remainin
2a150 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
2a160 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  he application-s
2a170 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2a180 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
2a190 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
2a1a0 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74  nted by a (lengt
2a1b0 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e  h, data) pair an
2a1c0 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
2a1d0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
2a1e0 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
2a1f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2a200 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
2a210 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
2a220 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
2a230 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
2a240 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
2a250 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
2a260 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
2a270 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
2a280 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
2a290 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2a2a0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
2a2b0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
2a2c0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
2a2d0 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
2a2e0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
2a2f0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  G2)..**.** ^The 
2a300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a310 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
2a320 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
2a330 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a340 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
2a350 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
2a360 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
2a370 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
2a380 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
2a390 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20  ollation.  ^The 
2a3a0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2a3b0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
2a3c0 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
2a3d0 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
2a3e0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
2a3f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a400 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
2a410 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
2a420 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a430 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e  ation_v2()..** ^
2a440 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
2a450 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
2a460 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
2a470 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
2a480 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
2a490 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
2a4a0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
2a4b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2a4c0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
2a4d0 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
2a4e0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
2a4f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a500 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2a510 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
2a520 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
2a530 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
2a540 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a550 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a560 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
2a570 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2a580 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2a590 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2a5a0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2a5b0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2a5c0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2a5d0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2a5e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a5f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2a600 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2a610 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2a620 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2a630 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2a640 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2a650 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2a660 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2a670 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2a680 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
2a690 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2a6a0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
2a6b0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2a6c0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
2a6d0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2a6e0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2a6f0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2a700 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2a710 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2a720 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2a730 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
2a740 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
2a750 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
2a760 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
2a770 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
2a780 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
2a790 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
2a7a0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
2a7b0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
2a7c0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
2a7d0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
2a7e0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2a7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2a800 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2a810 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
2a820 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2a830 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
2a840 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2a850 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
2a860 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
2a870 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
2a880 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
2a890 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
2a8a0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
2a8b0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
2a8c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2a8d0 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
2a8e0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2a8f0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
2a900 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2a910 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
2a920 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
2a930 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
2a940 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
2a950 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
2a960 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
2a970 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
2a980 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
2a990 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
2a9a0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
2a9b0 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
2a9c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2a9d0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
2a9e0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
2a9f0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
2aa00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2aa10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
2aa20 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
2aa30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
2aa40 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2aa50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
2aa60 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
2aa70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2aa80 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
2aa90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2aaa0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
2aab0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2aac0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
2aad0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
2aae0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
2aaf0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
2ab00 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
2ab10 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
2ab20 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
2ab30 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2ab40 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2ab50 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
2ab60 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
2ab70 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
2ab80 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
2ab90 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
2aba0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
2abb0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
2abc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2abd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2abe0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2abf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2ac00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2ac10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ac20 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
2ac30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2ac40 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
2ac50 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
2ac60 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
2ac70 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2ac80 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
2ac90 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
2aca0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2acb0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
2acc0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
2acd0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2ace0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2acf0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
2ad00 29 0a 29 3b 0a 0a 23 69 66 20 53 51 4c 49 54 45  ).);..#if SQLITE
2ad10 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
2ad20 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2ad30 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2ad40 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2ad50 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2ad60 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2ad70 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2ad80 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2ad90 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2ada0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2adb0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2adc0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2add0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2ade0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2adf0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2ae00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ae10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ae20 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2ae30 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2ae40 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2ae50 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2ae60 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2ae70 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2ae80 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2ae90 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2aea0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2aeb0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2aec0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2aed0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2aee0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2aef0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2af00 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2af10 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2af20 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2af30 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2af40 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2af50 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2af60 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2af70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2af80 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2af90 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2afa0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2afb0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2afc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2afd0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2afe0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2aff0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2b000 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2b010 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2b020 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
2b030 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2b040 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2b050 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
2b060 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2b070 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2b080 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
2b090 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2b0a0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2b0b0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2b0c0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
2b0d0 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
2b0e0 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
2b0f0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2b100 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
2b110 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
2b120 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2b130 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2b140 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
2b150 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2b160 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2b170 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2b180 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2b190 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2b1a0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2b1b0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2b1c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2b1d0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2b1e0 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2b1f0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
2b200 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
2b210 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
2b220 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
2b230 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
2b240 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
2b250 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
2b260 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
2b270 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
2b280 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2b290 5e 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e  ^If the operatin
2b2a0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
2b2b0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
2b2c0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
2b2d0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
2b2e0 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
2b2f0 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
2b300 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
2b310 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
2b320 20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75   second. ^The nu
2b330 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2b340 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
2b350 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
2b360 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
2b370 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
2b380 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b390 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
2b3a0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
2b3b0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
2b3c0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
2b3d0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
2b3e0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
2b3f0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74  ] object..*/.int
2b400 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
2b410 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b420 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
2b430 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2b440 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2b450 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
2b460 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2b470 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2b480 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2b490 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2b4a0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2b4b0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
2b4c0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
2b4d0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
2b4e0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
2b4f0 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
2b500 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
2b510 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
2b520 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2b530 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
2b540 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
2b550 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
2b560 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2b570 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
2b580 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2b590 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
2b5a0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
2b5b0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2b5c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2b5d0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2b5e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
2b5f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
2b600 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
2b610 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
2b620 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2b630 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2b640 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
2b650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b660 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
2b670 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2b680 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
2b690 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
2b6a0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2b6b0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2b6c0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2b6d0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2b6e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2b6f0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2b700 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2b710 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2b720 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
2b730 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2b740 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
2b750 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
2b760 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
2b770 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2b780 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
2b790 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2b7a0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
2b7b0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
2b7c0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2b7d0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2b7e0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
2b7f0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
2b800 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2b810 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
2b820 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
2b830 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
2b840 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2b850 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
2b860 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
2b870 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
2b880 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2b890 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
2b8a0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
2b8b0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
2b8c0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2b8d0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
2b8e0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
2b8f0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
2b900 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
2b910 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
2b920 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
2b930 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
2b940 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2b950 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2b960 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
2b970 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
2b980 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2b990 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
2b9a0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2b9b0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
2b9c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
2b9d0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
2b9e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b9f0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
2ba00 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
2ba10 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
2ba20 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
2ba30 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2ba40 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
2ba50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
2ba60 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
2ba70 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
2ba80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ba90 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
2baa0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
2bab0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
2bac0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
2bad0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
2bae0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
2baf0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2bb00 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2bb10 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2bb20 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2bb30 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
2bb40 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
2bb50 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
2bb60 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
2bb70 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
2bb80 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
2bb90 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
2bba0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
2bbb0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
2bbc0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
2bbd0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
2bbe0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
2bbf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2bc00 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2bc10 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
2bc20 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
2bc30 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
2bc40 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
2bc50 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
2bc60 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
2bc70 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
2bc80 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
2bc90 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2bca0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
2bcb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
2bcc0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
2bcd0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
2bce0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
2bcf0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
2bd00 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
2bd10 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
2bd20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2bd30 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
2bd40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
2bd50 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
2bd60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2bd70 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2bd80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bd90 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
2bda0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
2bdb0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2bdc0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2bdd0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2bde0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2bdf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2be00 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
2be10 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
2be20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2be30 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
2be40 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
2be50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
2be60 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
2be70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2be80 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
2be90 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
2bea0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
2beb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bec0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
2bed0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2bee0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
2bef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bf00 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
2bf10 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
2bf20 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
2bf30 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
2bf40 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
2bf50 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
2bf60 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
2bf70 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
2bf80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bf90 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
2bfa0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
2bfb0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
2bfc0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2bfd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2bfe0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
2bff0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c000 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
2c010 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
2c020 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2c030 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
2c040 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
2c050 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
2c060 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2c070 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c080 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
2c090 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2c0a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c0b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c0c0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
2c0d0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
2c0e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
2c0f0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
2c100 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
2c110 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
2c120 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
2c130 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c140 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
2c150 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
2c160 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2c170 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
2c180 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
2c190 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2c1a0 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
2c1b0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
2c1c0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
2c1d0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
2c1e0 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
2c1f0 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
2c200 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
2c210 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2c230 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
2c240 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2c250 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2c260 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2c270 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
2c280 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
2c290 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
2c2a0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
2c2b0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
2c2c0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
2c2d0 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
2c2e0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2c2f0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2c300 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2c310 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2c320 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2c330 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2c340 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2c350 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
2c360 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2c370 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2c380 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2c390 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2c3a0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2c3b0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2c3c0 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2c3d0 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2c3e0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2c3f0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2c400 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2c410 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2c420 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2c430 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2c440 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2c450 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
2c460 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
2c470 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2c480 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2c490 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
2c4a0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
2c4b0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
2c4c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2c4d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
2c4e0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
2c4f0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
2c500 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
2c510 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2c520 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
2c530 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2c540 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
2c550 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
2c560 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
2c570 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
2c580 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
2c590 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
2c5a0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2c5b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
2c5c0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
2c5d0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
2c5e0 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
2c5f0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
2c600 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
2c610 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
2c620 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
2c630 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
2c640 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
2c650 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
2c660 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
2c670 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
2c680 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2c690 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c6a0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2c6b0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2c6c0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2c6d0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2c6e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2c6f0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2c700 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
2c710 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
2c720 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2c730 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
2c740 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
2c750 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2c760 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
2c770 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
2c780 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
2c790 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
2c7a0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
2c7b0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
2c7c0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
2c7d0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
2c7e0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2c7f0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
2c800 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
2c810 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
2c820 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
2c830 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
2c840 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
2c850 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
2c860 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
2c870 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
2c880 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2c890 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2c8a0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2c8b0 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2c8c0 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2c8d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
2c8e0 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
2c8f0 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
2c900 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
2c910 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
2c920 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
2c930 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
2c940 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
2c950 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
2c960 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
2c970 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
2c980 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
2c990 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
2c9a0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
2c9b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
2c9c0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
2c9d0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
2c9e0 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
2c9f0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
2ca00 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
2ca10 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
2ca20 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
2ca30 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
2ca40 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2ca50 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2ca60 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2ca70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2ca80 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
2ca90 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2caa0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
2cab0 6f 73 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  osed..** ^The ro
2cac0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2cad0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2cae0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2caf0 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  is.** rolled bac
2cb00 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d  k because a comm
2cb10 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
2cb20 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a  rned non-zero..*
2cb30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2cb40 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2cb50 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
2cb60 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
2cb70 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2cb80 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2cb90 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2cba0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2cbb0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2cbc0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2cbd0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2cbe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cbf0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2cc00 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2cc10 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2cc20 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2cc30 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2cc40 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2cc50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
2cc60 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2cc70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cc80 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2cc90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2cca0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
2ccb0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
2ccc0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2ccd0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2cce0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
2ccf0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2cd00 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2cd10 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2cd20 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2cd30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cd40 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2cd50 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2cd60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2cd70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
2cd80 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
2cd90 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
2cda0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2cdb0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2cdc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2cdd0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2cde0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2cdf0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2ce00 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2ce10 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2ce20 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
2ce30 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2ce40 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2ce50 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2ce60 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2ce70 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2ce80 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2ce90 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2cea0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2ceb0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2cec0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2ced0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2cee0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
2cef0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2cf00 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
2cf10 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
2cf20 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
2cf30 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
2cf40 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
2cf50 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
2cf60 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2cf70 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
2cf80 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2cf90 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
2cfa0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2cfb0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2cfc0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2cfd0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2cfe0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
2cff0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2d000 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2d010 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2d020 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2d030 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2d040 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2d050 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
2d060 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
2d070 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2d080 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
2d090 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
2d0a0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
2d0b0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
2d0c0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
2d0d0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
2d0e0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
2d0f0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
2d100 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
2d110 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2d120 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2d130 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2d140 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2d150 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2d160 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2d170 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2d180 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2d190 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2d1a0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2d1b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2d1c0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2d1d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d1e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2d1f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2d200 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2d210 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d220 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2d230 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2d240 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2d250 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2d260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d270 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2d280 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2d290 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2d2a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d2b0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2d2c0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2d2d0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2d2e0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2d2f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d300 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2d310 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2d320 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2d330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2d340 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2d350 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2d360 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2d370 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d380 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
2d390 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
2d3a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
2d3b0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
2d3c0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
2d3d0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
2d3e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d3f0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
2d400 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
2d410 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
2d420 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2d430 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2d440 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2d450 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2d460 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2d470 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
2d480 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2d490 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2d4a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2d4b0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2d4c0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2d4d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2d4e0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2d4f0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2d500 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2d510 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
2d520 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
2d530 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
2d540 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2d550 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2d560 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2d570 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2d580 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2d590 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2d5a0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2d5b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d5c0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2d5d0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2d5e0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2d5f0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2d600 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2d610 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2d620 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2d630 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
2d640 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
2d650 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2d660 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2d670 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2d680 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2d690 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2d6a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2d6b0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2d6c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2d6d0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2d6e0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2d6f0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2d700 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2d710 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
2d720 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2d730 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2d740 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2d750 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2d760 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2d770 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2d780 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2d790 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2d7a0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2d7b0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2d7c0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2d7d0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2d7e0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2d7f0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2d800 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2d810 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
2d820 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2d830 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2d840 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
2d850 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
2d860 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
2d870 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
2d880 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2d890 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
2d8a0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
2d8b0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2d8c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2d8d0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2d8e0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2d8f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2d900 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2d910 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2d920 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2d930 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2d940 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2d950 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2d960 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2d970 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2d980 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
2d990 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
2d9a0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
2d9b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d9c0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2d9d0 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
2d9e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d9f0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2da00 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2da10 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
2da20 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
2da30 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
2da40 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
2da50 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
2da60 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
2da70 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
2da80 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
2da90 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2daa0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2dab0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2dac0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2dad0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2dae0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2daf0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
2db00 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
2db10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2db20 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
2db30 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
2db40 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
2db50 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
2db60 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
2db70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2db80 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2db90 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2dba0 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
2dbb0 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
2dbc0 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ze.**.** ^The sq
2dbd0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2dbe0 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2dbf0 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2dc00 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2dc10 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2dc20 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2dc30 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2dc40 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20   SQLite..** ^If 
2dc50 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
2dc60 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
2dc70 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
2dc80 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
2dc90 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
2dca0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2dcb0 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
2dcc0 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
2dcd0 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
2dce0 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
2dcf0 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
2dd00 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
2dd10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69  d..**.** ^The li
2dd20 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
2dd30 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20  oft" because if 
2dd40 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2dd50 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
2dd60 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
2dd70 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
2dd80 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
2dd90 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
2dda0 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
2ddb0 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
2ddc0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
2ddd0 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
2dde0 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
2ddf0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72  * ^A negative or
2de00 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2de10 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2de20 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2de30 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2de40 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2de50 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2de60 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2de70 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2de80 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  hausted..** ^The
2de90 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2dea0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2deb0 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2dec0 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d  **.** ^(SQLite m
2ded0 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2dee0 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2def0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2df00 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2df10 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2df20 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2df30 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2df40 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2df50 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2df60 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54  tification.)^  T
2df70 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
2df80 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  imit is.** calle
2df90 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
2dfa0 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
2dfb0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
2dfc0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
2dfd0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
2dfe0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
2dff0 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
2e000 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2e010 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
2e020 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
2e030 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e040 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2e050 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
2e060 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
2e070 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
2e080 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2e090 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
2e0a0 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
2e0b0 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
2e0c0 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
2e0d0 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
2e0e0 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2e0f0 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
2e100 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2e110 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
2e120 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
2e130 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
2e140 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
2e150 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
2e160 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
2e170 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
2e180 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2e190 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2e1a0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2e1b0 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2e1c0 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2e1d0 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2e1e0 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
2e1f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2e200 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2e210 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2e220 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2e230 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2e240 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2e250 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2e260 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2e270 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2e280 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2e290 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2e2a0 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2e2b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2e2c0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2e2d0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2e2e0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2e2f0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
2e300 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e310 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
2e320 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2e330 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
2e340 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
2e350 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2e360 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2e370 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2e380 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2e390 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
2e3a0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2e3b0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2e3c0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2e3d0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2e3e0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2e3f0 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2e400 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2e410 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2e420 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2e430 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2e440 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
2e450 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2e460 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2e470 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2e480 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2e490 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2e4a0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2e4b0 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2e4c0 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2e4d0 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2e4e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
2e4f0 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
2e500 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
2e510 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
2e520 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
2e530 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
2e540 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
2e550 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2e560 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
2e570 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2e580 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
2e590 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2e5a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
2e5b0 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
2e5c0 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
2e5d0 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
2e5e0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2e5f0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2e600 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
2e610 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
2e620 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
2e630 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
2e640 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
2e650 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
2e660 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
2e670 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
2e680 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
2e690 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
2e6a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2e6b0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
2e6c0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2e6d0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2e6e0 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
2e6f0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2e700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
2e710 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2e720 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2e730 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
2e740 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
2e750 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
2e760 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2e770 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2e780 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
2e790 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
2e7a0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2e7b0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
2e7c0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2e7d0 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2e7e0 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2e7f0 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2e800 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2e810 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2e820 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2e830 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2e840 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2e850 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2e860 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2e870 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2e880 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
2e890 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
2e8a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2e8b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2e8c0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2e8d0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
2e8e0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
2e8f0 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
2e900 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
2e910 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
2e920 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
2e930 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
2e940 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2e950 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2e960 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
2e970 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2e980 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
2e990 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
2e9a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2e9b0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2e9c0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
2e9d0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2e9e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2e9f0 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
2ea00 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
2ea10 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
2ea20 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
2ea30 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2ea40 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
2ea50 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
2ea60 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
2ea70 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
2ea80 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
2ea90 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
2eaa0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
2eab0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
2eac0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
2ead0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
2eae0 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
2eaf0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2eb00 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
2eb10 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
2eb20 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2eb30 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
2eb40 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
2eb50 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2eb60 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
2eb70 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
2eb80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2eb90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
2eba0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
2ebb0 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
2ebc0 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
2ebd0 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
2ebe0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2ebf0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2ec00 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2ec10 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2ec20 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2ec30 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2ec40 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
2ec50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
2ec60 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
2ec70 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
2ec80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ec90 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
2eca0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
2ecb0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
2ecc0 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
2ecd0 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
2ece0 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
2ecf0 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
2ed00 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
2ed10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ed20 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
2ed30 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
2ed40 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2ed50 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
2ed60 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
2ed70 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
2ed80 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
2ed90 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
2eda0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
2edb0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2edc0 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
2edd0 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
2ede0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2edf0 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
2ee00 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
2ee10 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
2ee20 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
2ee30 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2ee40 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
2ee50 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
2ee60 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
2ee70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2ee80 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2ee90 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
2eea0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
2eeb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
2eec0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
2eed0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2eee0 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
2eef0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
2ef00 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
2ef10 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
2ef20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ef30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2ef40 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2ef50 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
2ef60 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
2ef70 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
2ef80 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
2ef90 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
2efa0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
2efb0 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
2efc0 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
2efd0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
2efe0 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
2eff0 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
2f000 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
2f010 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
2f020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f030 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2f040 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f050 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
2f060 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
2f070 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2f080 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
2f090 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
2f0a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2f0b0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
2f0c0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
2f0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
2f0e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
2f0f0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
2f100 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
2f110 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
2f120 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2f130 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
2f140 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
2f150 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2f160 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
2f170 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
2f180 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
2f190 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
2f1a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2f1b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
2f1c0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
2f1d0 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
2f1e0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2f1f0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2f200 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
2f210 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
2f220 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
2f230 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
2f240 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
2f250 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2f260 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
2f270 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
2f280 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f290 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
2f2a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2f2b0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
2f2c0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2f2d0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
2f2e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
2f2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
2f300 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
2f310 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
2f320 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
2f330 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
2f340 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
2f350 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
2f360 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
2f370 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
2f380 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
2f390 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
2f3a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
2f3b0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
2f3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f3d0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
2f3e0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
2f3f0 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
2f400 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
2f410 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
2f420 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
2f430 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
2f440 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
2f450 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
2f460 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
2f470 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
2f480 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
2f490 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
2f4a0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
2f4b0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
2f4c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
2f4d0 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
2f4e0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
2f4f0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2f500 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
2f510 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
2f520 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
2f530 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
2f540 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
2f550 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
2f560 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
2f570 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2f580 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
2f590 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
2f5a0 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
2f5b0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
2f5c0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
2f5d0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
2f5e0 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
2f5f0 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
2f600 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
2f610 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
2f620 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
2f630 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
2f640 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
2f650 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
2f660 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
2f670 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
2f680 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
2f690 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
2f6a0 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
2f6b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
2f6c0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
2f6d0 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
2f6e0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
2f6f0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b  .** to all new [
2f700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f710 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ions]..**.** ^(T
2f720 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
2f730 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
2f740 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e  the extension en
2f750 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20  try point.** in 
2f760 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
2f770 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2f780 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2f790 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a  ].  That memory.
2f7a0 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65  ** is deallocate
2f7b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65  d by [sqlite3_re
2f7c0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2f7d0 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  on()].)^.**.** ^
2f7e0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
2f7f0 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
2f800 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
2f810 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f   that is.** auto
2f820 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
2f830 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
2f840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f850 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65  ction].** is ope
2f860 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
2f870 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2f880 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
2f890 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
2f8a0 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44  pen_v2()]..** ^D
2f8b0 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
2f8c0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
2f8d0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
2f8e0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74   routine.** mult
2f8f0 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20  iple times with 
2f900 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
2f910 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
2f920 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78  ** ^Automatic ex
2f930 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2f940 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2f950 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2f960 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2f970 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2f980 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2f990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f9a0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2f9b0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
2f9c0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
2f9d0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2f9e0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2f9f0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2fa00 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2fa10 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20  . It undoes the 
2fa20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
2fa30 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
2fa40 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2fa50 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a  ] calls.)^.**.**
2fa60 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
2fa70 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
2fa80 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
2fa90 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
2faa0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fab0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2fac0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
2fad0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
2fae0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
2faf0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
2fb00 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
2fb10 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
2fb20 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
2fb30 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
2fb40 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
2fb50 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
2fb60 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
2fb70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
2fb80 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
2fb90 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
2fba0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
2fbb0 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
2fbc0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
2fbd0 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
2fbe0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
2fbf0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
2fc00 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
2fc10 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
2fc20 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
2fc30 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
2fc40 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
2fc50 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
2fc60 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
2fc70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2fc80 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
2fc90 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
2fca0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2fcb0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
2fcc0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
2fcd0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2fce0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fcf0 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
2fd00 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
2fd10 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
2fd20 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
2fd30 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
2fd40 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
2fd50 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  able Object.** K
2fd60 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
2fd70 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
2fd80 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
2fd90 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
2fda0 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
2fdb0 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
2fdc0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
2fdd0 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
2fde0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2fdf0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
2fe00 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
2fe10 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
2fe20 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
2fe30 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2fe40 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
2fe50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
2fe60 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
2fe70 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
2fe80 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
2fe90 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
2fea0 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
2feb0 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
2fec0 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
2fed0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
2fee0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
2fef0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2ff00 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
2ff10 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
2ff20 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
2ff30 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
2ff40 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
2ff50 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
2ff60 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
2ff70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ff80 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
2ff90 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
2ffa0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
2ffb0 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
2ffc0 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
2ffd0 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
2ffe0 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
2fff0 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
30000 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
30010 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
30020 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
30030 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
30040 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
30050 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
30060 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
30070 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
30080 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
30090 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
300a0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
300b0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
300c0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
300d0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
300e0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
300f0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
30100 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30110 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
30120 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
30130 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
30140 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
30150 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
30160 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
30170 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
30180 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
30190 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
301a0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
301b0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
301c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
301d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
301e0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
301f0 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
30200 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
30210 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
30220 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
30230 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
30240 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
30250 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
30260 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
30270 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
30280 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
30290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
302a0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
302b0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
302c0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
302d0 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
302e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
302f0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
30300 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
30310 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
30320 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
30330 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
30340 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30350 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
30360 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
30370 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
30380 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
30390 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
303a0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
303b0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
303c0 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
303d0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
303e0 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
303f0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30400 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
30410 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
30420 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30430 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
30440 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30450 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
30460 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
30470 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
30480 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
30490 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
304a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
304b0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
304c0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
304d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
304e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
304f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30500 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
30510 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
30520 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
30530 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
30540 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
30550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
30560 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
30570 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
30580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
30590 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
305a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
305b0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
305c0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
305d0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
305e0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
305f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
30600 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
30610 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
30620 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
30630 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
30640 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30650 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
30660 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
30670 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
30680 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
30690 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
306a0 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
306b0 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
306c0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
306d0 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
306e0 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lds..**.** ^(The
306f0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
30700 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
30710 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
30720 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  aints of the for
30730 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f  m:.**.** <pre>co
30740 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72  lumn OP expr</pr
30750 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f  e>.**.** where O
30760 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
30770 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
30780 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61  t;=.)^  ^(The pa
30790 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
307a0 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
307b0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
307c0 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64  op.)^  ^(The ind
307d0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
307e0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
307f0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
30800 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f  Column.)^  ^(aCo
30810 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
30820 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
30830 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
30840 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
30850 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
30860 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
30870 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
30880 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
30890 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29  e if it cannot.)
308a0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74  ^.**.** ^The opt
308b0 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
308c0 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
308d0 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
308e0 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
308f0 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
30900 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
30910 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
30920 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
30930 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
30940 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
30950 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
30960 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
30970 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
30980 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72  .** ^The aConstr
30990 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
309a0 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
309b0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61  clause terms tha
309c0 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e  t are.** relevan
309d0 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  t to the particu
309e0 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
309f0 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
30a00 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74  .**.** ^Informat
30a10 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
30a20 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
30a30 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
30a40 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20  rBy[]..** ^Each 
30a50 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
30a60 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
30a70 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
30a80 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
30a90 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  The [xBestIndex]
30aa0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
30ab0 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
30ac0 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
30ad0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
30ae0 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
30af0 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
30b00 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65  r.  ^If argvInde
30b10 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
30b20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
30b30 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
30b40 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
30b50 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
30b60 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
30b70 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
30b80 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
30b90 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^(If aConstraint
30ba0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
30bb0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
30bc0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
30bd0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
30be0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
30bf0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
30c00 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
30c10 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
30c20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  SQLite.)^.**.** 
30c30 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20  ^The idxNum and 
30c40 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
30c50 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
30c60 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
30c70 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
30c80 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33  od..** ^[sqlite3
30c90 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
30ca0 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
30cb0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
30cc0 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
30cd0 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
30ce0 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f  * ^The orderByCo
30cf0 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
30d00 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
30d10 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
30d20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
30d30 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
30d40 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
30d50 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
30d60 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
30d70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
30d80 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
30d90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73  d..**.** ^The es
30da0 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
30db0 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
30dc0 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
30dd0 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
30de0 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
30df0 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
30e00 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
30e10 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
30e20 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
30e30 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
30e40 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
30e50 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
30e60 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
30e70 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
30e80 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
30e90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
30ea0 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
30eb0 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
30ec0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
30ed0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
30ee0 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
30ef0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
30f00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
30f10 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
30f20 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
30f30 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
30f40 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
30f50 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
30f60 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
30f70 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
30f80 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
30f90 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
30fa0 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
30fb0 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
30fc0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
30fd0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
30fe0 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
30ff0 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
31000 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
31010 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
31020 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
31030 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
31040 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
31050 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
31060 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
31070 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
31080 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
31090 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
310a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
310b0 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
310c0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
310d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
310e0 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
310f0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
31100 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
31110 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
31120 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
31130 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
31140 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
31150 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
31160 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
31170 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
31180 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
31190 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
311a0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
311b0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
311c0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
311d0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
311e0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
311f0 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
31200 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
31210 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
31220 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
31230 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
31240 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
31250 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
31260 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
31270 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
31280 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
31290 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
312a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
312b0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
312c0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
312d0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
312e0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
312f0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
31300 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
31310 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
31320 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
31330 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
31340 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
31350 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
31360 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
31370 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
31380 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
31390 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
313a0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
313b0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
313c0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
313d0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
313e0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
313f0 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
31400 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
31410 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
31420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
31430 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
31440 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
31450 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
31460 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
31470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
31480 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
31490 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
314a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
314b0 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
314c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
314d0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
314e0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
314f0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
31500 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
31510 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
31520 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
31530 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
31540 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e   to register a n
31550 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
31560 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a  e module] name..
31570 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73  ** ^Module names
31580 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65   must be registe
31590 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72  red before.** cr
315a0 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69  eating a new [vi
315b0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69  rtual table] usi
315c0 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  ng the module an
315d0 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61  d before using a
315e0 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20  .** preexisting 
315f0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
31600 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
31610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c  **.** ^The modul
31620 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
31630 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
31640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31650 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
31660 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
31670 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d  meter.  ^The nam
31680 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
31690 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  is given by the 
316a0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
316b0 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72  eter.  ^The thir
316c0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
316d0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74   pointer to.** t
316e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
316f0 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  n of the [virtua
31700 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
31710 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a     ^The fourth.*
31720 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  * parameter is a
31730 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65  n arbitrary clie
31740 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  nt data pointer 
31750 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
31760 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74  hrough.** into t
31770 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
31780 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
31790 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  ods of the virtu
317a0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a  al table module.
317b0 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69  ** when a new vi
317c0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62  rtual table is b
317d0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
317e0 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64  or reinitialized
317f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31800 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
31810 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  le_v2() interfac
31820 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61  e has a fifth pa
31830 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
31840 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
31850 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
31860 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  r the pClientDat
31870 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  a.  ^SQLite will
31880 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
31890 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
318a0 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
318b0 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
318c0 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
318d0 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
318e0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
318f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
31900 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20  ate_module().** 
31910 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75  interface is equ
31920 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74  ivalent to sqlit
31930 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
31940 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
31950 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e  L.** destructor.
31960 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31970 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
31980 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
31990 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
319a0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
319b0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
319c0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
319d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
319e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
319f0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
31a00 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
31a10 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
31a20 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
31a30 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
31a40 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20  id *pClientData 
31a50 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
31a60 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
31a70 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
31a80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
31a90 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
31aa0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
31ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31ac0 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
31ad0 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
31ae0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
31af0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31b00 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
31b10 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
31b20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
31b30 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
31b40 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
31b50 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
31b60 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
31b70 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a,         /* Cl
31b80 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
31b90 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
31ba0 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  /.  void(*xDestr
31bb0 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f  oy)(void*)     /
31bc0 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63  * Module destruc
31bd0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  tor function */.
31be0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31bf0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
31c00 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63  e Instance Objec
31c10 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
31c20 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a  qlite3_vtab.**.*
31c30 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c  * Every [virtual
31c40 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69   table module] i
31c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
31c60 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a  es a subclass.**
31c70 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
31c80 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
31c90 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
31ca0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  e.** of the [vir
31cb0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61  tual table].  Ea
31cc0 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
31cd0 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
31ce0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
31cf0 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
31d00 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
31d10 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f  on..** The purpo
31d20 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
31d30 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
31d40 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
31d50 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f  s that are.** co
31d60 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  mmon to all modu
31d70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31d80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75  ns..**.** ^Virtu
31d90 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
31da0 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
31db0 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
31dc0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
31dd0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
31de0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
31df0 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67  tf()] to zErrMsg
31e00 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68  .  The method sh
31e10 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72  ould.** take car
31e20 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72  e that any prior
31e30 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64   string is freed
31e40 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   by a call to [s
31e50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a  qlite3_free()].*
31e60 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67  * prior to assig
31e70 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e  ning a new strin
31e80 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e  g to zErrMsg.  ^
31e90 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  After the error 
31ea0 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65  message.** is de
31eb0 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68  livered up to th
31ec0 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61  e client applica
31ed0 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67  tion, the string
31ee0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
31ef0 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20  ically.** freed 
31f00 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  by sqlite3_free(
31f10 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73  ) and the zErrMs
31f20 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20  g field will be 
31f30 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63  zeroed..*/.struc
31f40 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b  t sqlite3_vtab {
31f50 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
31f60 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65  _module *pModule
31f70 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65  ;  /* The module
31f80 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61   for this virtua
31f90 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74  l table */.  int
31fa0 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20   nRef;          
31fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31fc0 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a  NO LONGER USED *
31fd0 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  /.  char *zErrMs
31fe0 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g;              
31ff0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73      /* Error mes
32000 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  sage from sqlite
32010 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20  3_mprintf() */. 
32020 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
32030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32040 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
32050 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
32060 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
32070 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
32080 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73  rtual Table Curs
32090 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  or Object.** KEY
320a0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
320b0 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
320c0 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
320d0 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  }.**.** Every [v
320e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
320f0 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
32100 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
32110 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
32120 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
32130 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
32140 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
32150 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
32160 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
32170 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
32180 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
32190 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
321a0 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
321b0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
321c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
321d0 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
321e0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
321f0 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
32200 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
32210 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
32220 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
32230 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73  e] method.  Curs
32240 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
32250 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
32260 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
32270 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
32280 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
32290 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
322a0 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
322b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
322c0 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
322d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
322e0 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
322f0 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
32300 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
32310 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
32320 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
32330 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
32340 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
32350 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
32360 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
32370 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
32380 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
32390 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
323a0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
323b0 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
323c0 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
323d0 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
323e0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
323f0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
32400 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
32410 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
32420 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
32430 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
32440 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
32450 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
32460 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65  ** ^The [xCreate
32470 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
32480 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a   methods of a.**
32490 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
324a0 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69  module] call thi
324b0 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  s interface.** t
324c0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
324d0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
324e0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
324f0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
32500 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
32510 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
32520 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ement..*/.int sq
32530 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
32540 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
32550 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
32560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32570 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
32580 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
32590 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
325a0 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20  (Virtual tables 
325b0 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
325c0 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
325d0 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
325e0 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
325f0 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
32600 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
32610 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
32620 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
32630 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
32640 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
32650 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
32660 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
32670 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a   overloaded.)^.*
32680 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20  *.** ^(This API 
32690 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f  makes sure a glo
326a0 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61  bal version of a
326b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
326c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e   particular.** n
326d0 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f  ame and number o
326e0 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69  f parameters exi
326f0 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68  sts.  If no such
32700 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73   function exists
32710 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20  .** before this 
32720 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61  API is called, a
32730 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
32740 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68   created.)^  ^Th
32750 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32760 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
32770 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
32780 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
32790 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
327a0 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
327b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
327c0 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
327d0 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
327e0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
327f0 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
32800 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  ceholder functio
32810 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
32820 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61  erloaded.** by a
32830 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
32840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32850 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
32860 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
32870 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
32880 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
32890 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
328a0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
328b0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
328c0 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
328d0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
328e0 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
328f0 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
32900 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
32910 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
32920 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
32930 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
32940 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
32950 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
32960 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
32970 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
32980 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
32990 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
329a0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
329b0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
329c0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
329d0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
329e0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
329f0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
32a00 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
32a10 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
32a20 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
32a30 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
32a40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
32a50 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
32a60 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20  An Open BLOB.** 
32a70 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
32a80 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
32a90 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
32aa0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
32ab0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
32ac0 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
32ad0 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
32ae0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
32af0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
32b00 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
32b10 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a  rformed..** ^Obj
32b20 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
32b30 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
32b40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
32b50 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
32b60 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
32b70 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
32b80 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  ]..** ^The [sqli
32b90 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
32ba0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
32bb0 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
32bc0 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
32bd0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
32be0 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
32bf0 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
32c00 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  BLOB..** ^The [s
32c10 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
32c20 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  s()] interface r
32c30 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
32c40 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62  of the BLOB in b
32c50 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
32c60 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
32c70 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
32c80 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
32c90 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
32ca0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
32cb0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  I/O.**.** ^(This
32cc0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e   interfaces open
32cd0 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s a [BLOB handle
32ce0 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68   | handle] to th
32cf0 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a  e BLOB located.*
32d00 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63  * in row iRow, c
32d10 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74  olumn zColumn, t
32d20 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64  able zTable in d
32d30 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20  atabase zDb;.** 
32d40 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
32d50 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68  the same BLOB th
32d60 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
32d70 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
32d80 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
32d90 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
32da0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
32db0 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b   [rowid] = iRow;
32dc0 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
32dd0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73  ** ^If the flags
32de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
32df0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
32e00 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
32e10 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20  for read.** and 
32e20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49  write access. ^I
32e30 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
32e40 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
32e50 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
32e60 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20  ..** ^It is not 
32e70 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
32e80 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
32e90 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64  s part of an ind
32ea0 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a  ex or primary .*
32eb0 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e  * key for writin
32ec0 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20  g. ^If [foreign 
32ed0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
32ee0 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74   are enabled, it
32ef0 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73   is .** not poss
32f00 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
32f10 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
32f20 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b  rt of a [child k
32f30 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  ey] for writing.
32f40 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
32f50 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
32f60 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
32f70 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
32f80 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
32f90 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
32fa0 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
32fb0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
32fc0 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61  se that.** appea
32fd0 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20  rs after the AS 
32fe0 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65  keyword when the
32ff0 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e   database is con
33000 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54  nected using [AT
33010 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74  TACH]..** ^For t
33020 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
33030 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62   file, the datab
33040 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69  ase name is "mai
33050 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50  n"..** ^For TEMP
33060 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74   tables, the dat
33070 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74  abase name is "t
33080 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  emp"..**.** ^(On
33090 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
330a0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
330b0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42  d and the new [B
330c0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  LOB handle] is w
330d0 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70  ritten.** to *pp
330e0 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20  Blob. Otherwise 
330f0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
33100 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
33110 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a  *ppBlob is set.*
33120 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70  * to be a null p
33130 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68  ointer.)^.** ^Th
33140 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
33150 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33160 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
33170 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
33180 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
33190 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
331a0 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
331b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
331c0 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
331d0 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74  nctions. ^Note t
331e0 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
331f0 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
33200 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
33210 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
33220 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
33230 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
33240 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
33250 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
33260 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
33270 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
33280 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
33290 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  e..**.** ^(If th
332a0 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f  e row that a BLO
332b0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20  B handle points 
332c0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62  to is modified b
332d0 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  y an.** [UPDATE]
332e0 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62  , [DELETE], or b
332f0 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  y [ON CONFLICT] 
33300 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20  side-effects.** 
33310 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61  then the BLOB ha
33320 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61  ndle is marked a
33330 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20  s "expired"..** 
33340 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20  This is true if 
33350 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  any column of th
33360 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64  e row is changed
33370 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a  , even a column.
33380 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  ** other than th
33390 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68  e one the BLOB h
333a0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e  andle is open on
333b0 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .)^.** ^Calls to
333c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
333d0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
333e0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
333f0 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72  ] for.** a expir
33400 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66  ed BLOB handle f
33410 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75  ail with an retu
33420 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
33430 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28  TE_ABORT]..** ^(
33440 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20  Changes written 
33450 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f  into a BLOB prio
33460 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78  r to the BLOB ex
33470 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a  piring are not.*
33480 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  * rolled back by
33490 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
334a0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
334b0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
334c0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
334d0 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
334e0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
334f0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
33500 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68  )^.**.** ^Use th
33510 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
33520 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
33530 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
33540 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
33550 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
33560 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20   ^The size of a 
33570 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
33580 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
33590 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
335a0 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
335b0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
335c0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
335d0 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
335e0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
335f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
33600 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
33610 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
33620 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
33630 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
33640 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
33650 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
33660 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
33670 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
33680 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
33690 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
336a0 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
336b0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
336c0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
336d0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
336e0 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
336f0 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
33700 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
33710 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
33720 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
33730 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
33740 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69  b_close()]..*/.i
33750 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33760 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
33770 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
33780 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
33790 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
337a0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
337b0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
337c0 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
337d0 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
337e0 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
337f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33800 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
33810 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
33820 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
33830 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
33840 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
33850 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
33860 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
33870 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
33880 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
33890 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
338a0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
338b0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
338c0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
338d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
338e0 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
338f0 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
33900 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
33910 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
33920 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
33930 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
33940 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
33950 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
33960 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
33970 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
33980 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
33990 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
339a0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
339b0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
339c0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
339d0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
339e0 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
339f0 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
33a00 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
33a10 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
33a20 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
33a30 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
33a40 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
33a50 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
33a60 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
33a70 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
33a80 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
33a90 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
33aa0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
33ab0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
33ac0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
33ad0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
33ae0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
33af0 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
33b00 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
33b10 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
33b20 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
33b30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33b40 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
33b50 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33b60 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
33b70 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
33b80 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
33b90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33ba0 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
33bb0 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
33bc0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
33bd0 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
33be0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
33bf0 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
33c00 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
33c10 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
33c20 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
33c30 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
33c40 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
33c50 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
33c60 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
33c70 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
33c80 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
33c90 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
33ca0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
33cb0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
33cc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33cd0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33ce0 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33cf0 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33d00 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
33d10 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
33d20 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33d30 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
33d40 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
33d50 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
33d60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33d70 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
33d80 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33d90 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33da0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33db0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33dc0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33dd0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33de0 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
33df0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
33e00 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
33e10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33e20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
33e30 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
33e40 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
33e50 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
33e60 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
33e70 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
33e80 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
33e90 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
33ea0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
33eb0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
33ec0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
33ed0 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
33ee0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
33ef0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
33f00 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
33f10 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
33f20 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
33f30 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
33f40 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
33f50 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
33f60 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
33f70 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
33f80 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
33f90 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
33fa0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
33fb0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
33fc0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
33fd0 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
33fe0 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
33ff0 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
34000 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
34010 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
34020 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
34030 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
34040 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
34050 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
34060 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
34070 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
34080 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
34090 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
340a0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
340b0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
340c0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
340d0 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
340e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
340f0 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
34100 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
34110 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
34120 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
34130 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
34140 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
34150 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34160 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
34170 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
34180 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
34190 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
341a0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
341b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
341c0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
341d0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
341e0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
341f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34200 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
34210 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
34220 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
34230 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
34240 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
34250 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
34260 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
34270 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34280 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
34290 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
342a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
342b0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
342c0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
342d0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
342e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
342f0 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
34300 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
34310 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
34320 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
34330 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
34340 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
34350 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
34360 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
34370 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
34380 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
34390 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
343a0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
343b0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
343c0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
343d0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
343e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
343f0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
34400 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
34410 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
34420 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
34430 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
34440 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
34450 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
34460 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
34470 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
34480 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
34490 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
344a0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
344b0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
344c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
344d0 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73   the BLOB; it is
344e0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
344f0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
34500 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20   size of a BLOB 
34510 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a  using this API..
34520 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
34530 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
34540 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
34550 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
34560 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
34570 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
34580 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
34590 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20  s written.  ^If 
345a0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
345b0 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
345c0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
345d0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
345e0 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
345f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
34600 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
34610 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
34620 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
34630 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
34640 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
34650 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34660 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
34670 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
34680 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
34690 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
346a0 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
346b0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
346c0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
346d0 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20  T].  ^Writes to 
346e0 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63  the BLOB that oc
346f0 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65  curred.** before
34700 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
34710 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e  e] expired are n
34720 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ot rolled back b
34730 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74  y the.** expirat
34740 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c  ion of the handl
34750 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  e, though of cou
34760 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65  rse those change
34770 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20  s might.** have 
34780 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e  been overwritten
34790 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
347a0 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74  t that expired t
347b0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a  he BLOB handle.*
347c0 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e  * or by other in
347d0 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d  dependent statem
347e0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ents..**.** ^(On
347f0 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
34800 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72  3_blob_write() r
34810 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
34820 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
34830 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
34840 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34850 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34860 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
34870 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
34880 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34890 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
348a0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
348b0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
348c0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
348d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
348e0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
348f0 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34900 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34910 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34920 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
34930 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
34940 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
34950 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34960 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34970 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
34980 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34990 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
349a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
349b0 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ad()]..*/.int sq
349c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
349d0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
349e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
349f0 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
34a00 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
34a10 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
34a20 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
34a30 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
34a40 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
34a50 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
34a60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
34a70 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
34a80 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
34a90 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
34aa0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
34ab0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
34ac0 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
34ad0 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
34ae0 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
34af0 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
34b00 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
34b10 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
34b20 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
34b30 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
34b40 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
34b50 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
34b60 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
34b70 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
34b80 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rovided..**.** ^
34b90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
34ba0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
34bb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34bc0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
34bd0 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  n its name..** ^
34be0 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
34bf0 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61  ensitive..** ^Na
34c00 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
34c10 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
34c20 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  rings..** ^If th
34c30 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
34c40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34c50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
34c60 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20  ^If zVfsName is 
34c70 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
34c80 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74  fault VFS is ret
34c90 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65  urned..**.** ^Ne
34ca0 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
34cb0 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
34cc0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
34cd0 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77  ()..** ^Each new
34ce0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
34cf0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
34d00 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34d10 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  g is set..** ^Th
34d20 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
34d30 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
34d40 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
34d50 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e  out injury..** ^
34d60 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
34d70 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
34d80 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
34d90 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
34da0 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
34db0 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
34dc0 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
34dd0 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
34de0 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
34df0 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
34e00 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
34e10 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
34e20 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
34e30 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
34e40 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
34e50 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
34e60 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
34e70 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
34e80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69  d..**.** ^Unregi
34e90 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
34ea0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
34eb0 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
34ec0 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20  erface..** ^(If 
34ed0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
34ee0 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
34ef0 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
34f00 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
34f10 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
34f20 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
34f30 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
34f40 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ry.)^.*/.sqlite3
34f50 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
34f60 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
34f70 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
34f80 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
34f90 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
34fa0 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
34fb0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
34fc0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
34fd0 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
34fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34ff0 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
35000 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
35010 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
35020 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
35030 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
35040 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
35050 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
35060 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
35070 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
35080 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
35090 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
350a0 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
350b0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
350c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
350d0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
350e0 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
350f0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
35100 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ons.** of these 
35110 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20  mutex routines. 
35120 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   An appropriate 
35130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
35140 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75  * is selected au
35150 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63  tomatically at c
35160 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28  ompile-time.  ^(
35170 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
35180 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35190 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
351a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
351b0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
351c0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
351d0 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
351e0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
351f0 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
35200 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
35210 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
35220 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
35230 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
35240 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
35250 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
35260 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
35270 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
35280 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
35290 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
352a0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
352b0 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
352c0 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
352d0 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51  cation.  ^The SQ
352e0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
352f0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
35300 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
35310 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
35320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
35330 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
35340 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32   for use on OS/2
35350 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64  , Unix, and Wind
35360 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ows..**.** ^(If 
35370 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
35380 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
35390 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
353a0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
353b0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
353c0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
353d0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
353e0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
353f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35400 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
35410 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
35420 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
35430 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
35440 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
35450 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
35460 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
35470 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
35480 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
35490 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
354a0 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
354b0 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
354c0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
354d0 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
354e0 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
354f0 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
35500 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
35510 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
35520 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
35530 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
35540 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
35550 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
35560 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
35570 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35580 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75   it. ^If it retu
35590 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
355a0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
355b0 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
355c0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51   allocated.  ^SQ
355d0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
355e0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
355f0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
35600 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  r.  ^(The argume
35610 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
35620 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
35630 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
35640 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
35650 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35660 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35670 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
35680 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
35690 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
356a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
356b0 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
356c0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
356d0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
356e0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
356f0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
35700 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35710 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
35720 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35730 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
35740 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
35750 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
35760 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  RU2.** </ul>)^.*
35770 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
35780 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53  two constants (S
35790 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
357a0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
357b0 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20  X_RECURSIVE).** 
357c0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
357d0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
357e0 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
357f0 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20  utex.  ^The new 
35800 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
35810 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
35820 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
35830 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
35840 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
35850 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
35860 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
35870 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
35880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
35890 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
358a0 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
358b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
358c0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
358d0 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
358e0 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
358f0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
35900 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  to.  ^SQLite wil
35910 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
35920 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
35930 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
35940 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
35950 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66  ds one.  ^If a f
35960 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
35970 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
35980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
35990 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
359a0 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
359b0 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
359c0 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
359d0 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
359e0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
359f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
35a00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68  ..**.** ^The oth
35a10 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
35a20 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
35a30 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28  _mutex_alloc() (
35a40 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a  anything other.*
35a50 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55  * than SQLITE_MU
35a60 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
35a70 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
35a80 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e  IVE) each return
35a90 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
35aa0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
35ab0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53  sting mutex.  ^S
35ac0 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
35ad0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
35ae0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
35af0 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
35b00 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
35b10 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
35b20 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
35b30 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
35b40 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
35b50 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
35b60 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
35b70 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
35b80 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
35b90 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
35ba0 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
35bb0 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
35bc0 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
35bd0 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
35be0 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
35bf0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35c00 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
35c10 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
35c20 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
35c30 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
35c40 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
35c50 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
35c60 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
35c70 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
35c80 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
35c90 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
35ca0 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
35cb0 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20  ery call.  ^But 
35cc0 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
35cd0 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
35ce0 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
35cf0 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
35d00 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
35d10 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
35d20 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
35d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
35d40 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
35d50 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
35d60 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
35d70 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
35d80 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20  mutex.  ^SQLite 
35d90 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
35da0 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
35db0 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
35dc0 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
35dd0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
35de0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
35df0 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
35e00 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
35e10 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
35e20 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
35e30 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
35e40 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
35e50 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
35e60 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76  or.  ^SQLite nev
35e70 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
35e80 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
35e90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35ea0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35eb0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
35ec0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
35ed0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
35ee0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
35ef0 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68    ^If another th
35f00 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
35f10 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
35f20 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
35f30 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
35f40 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
35f50 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
35f60 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
35f70 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20  ITE_BUSY.  ^The 
35f80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
35f90 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
35fa0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
35fb0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
35fc0 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d  sful entry.  ^(M
35fd0 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
35fe0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
35ff0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
36000 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
36010 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
36020 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
36030 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65  .** In such case
36040 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
36050 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
36060 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
36070 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
36080 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
36090 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e   can enter.)^  ^
360a0 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72  (If the same thr
360b0 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
360c0 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  er any other.** 
360d0 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f  kind of mutex mo
360e0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
360f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
36100 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69  defined..** SQLi
36110 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
36120 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
36130 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
36140 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
36150 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65  .)^.**.** ^(Some
36160 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
36170 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
36180 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
36190 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
361a0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
361b0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
361c0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
361d0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
361e0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
361f0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
36200 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
36210 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
36220 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
36230 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
36240 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
36250 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
36260 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
36270 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a   behavior.)^.**.
36280 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36290 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
362a0 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
362b0 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
362c0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
362d0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
362e0 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62  hread.   ^(The b
362f0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
36300 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
36310 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
36320 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
36330 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
36340 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
36350 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
36360 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
36370 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
36380 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ither.)^.**.** ^
36390 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
363a0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
363b0 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
363c0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
363d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
363e0 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
363f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
36400 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
36410 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
36420 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
36430 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36440 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
36450 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
36460 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
36470 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
36480 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
36490 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
364a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
364b0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
364c0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
364d0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
364e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
364f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
36500 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
36510 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
36520 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
36530 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36550 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
36560 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
36570 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
36580 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
36590 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
365a0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
365b0 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
365c0 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
365d0 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
365e0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
365f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36600 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
36610 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
36620 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
36630 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
36640 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
36650 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
36660 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
36670 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
36680 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
36690 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
366a0 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
366b0 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
366c0 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
366d0 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
366e0 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
366f0 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
36700 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
36710 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
36720 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
36730 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
36740 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
36750 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
36760 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
36770 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
36780 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
36790 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
367a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
367b0 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
367c0 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
367d0 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
367e0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
367f0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
36800 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
36810 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
36820 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
36830 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  n..**.** ^The xM
36840 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
36850 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
36860 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
36870 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
36880 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
36890 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
368a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
368b0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
368c0 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69  * ^The xMutexIni
368d0 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  t routine is cal
368e0 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61  le by SQLite exa
368f0 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
36900 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
36910 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36920 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
36930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
36940 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69  xEnd method defi
36950 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
36960 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
36970 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
36980 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62  ystem shutdown b
36990 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  y the sqlite3_sh
369a0 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f  utdown() functio
369b0 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  n. The.** implem
369c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73  entation of this
369d0 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63   method is expec
369e0 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61  ted to release a
369f0 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  ll outstanding.*
36a00 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61  * resources obta
36a10 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65  ined by the mute
36a20 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d  x methods implem
36a30 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69  entation, especi
36a40 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62  ally.** those ob
36a50 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d  tained by the xM
36a60 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e  utexInit method.
36a70 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64    ^The xMutexEnd
36a80 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
36a90 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  is invoked exact
36aa0 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
36ab0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36ac0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
36ad0 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69  *.** ^(The remai
36ae0 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f  ning seven metho
36af0 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  ds defined by th
36b00 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d  is structure (xM
36b10 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d  utexAlloc,.** xM
36b20 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78  utexFree, xMutex
36b30 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79  Enter, xMutexTry
36b40 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78  , xMutexLeave, x
36b50 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a  MutexHeld and.**
36b60 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20   xMutexNotheld) 
36b70 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f  implement the fo
36b80 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
36b90 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79  es (respectively
36ba0 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ):.**.** <ul>.**
36bb0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36bc0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
36bd0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36be0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
36bf0 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _free()] </li>.*
36c00 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36c10 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36c20 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
36c30 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36c40 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  x_try()] </li>.*
36c50 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36c60 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
36c70 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
36c80 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36c90 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  x_held()] </li>.
36ca0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
36cb0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
36cc0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  d()] </li>.** </
36cd0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
36ce0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
36cf0 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
36d00 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
36d10 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
36d20 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
36d30 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
36d40 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
36d50 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
36d60 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
36d70 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36d80 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
36d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
36da0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
36db0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
36dc0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
36dd0 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
36de0 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
36df0 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
36e00 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
36e10 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
36e20 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36e30 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
36e40 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
36e50 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
36e60 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
36e70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
36e80 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
36e90 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
36ea0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
36eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
36ec0 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
36ed0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
36ee0 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20  e.  ^It must be 
36ef0 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69  harmless to.** i
36f00 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74  nvoke xMutexInit
36f10 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73  () mutiple times
36f20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
36f30 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74   process and wit
36f40 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e  hout.** interven
36f50 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75  ing calls to xMu
36f60 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e  texEnd().  Secon
36f70 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
36f80 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75   calls to.** xMu
36f90 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62  texInit() must b
36fa0 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  e no-ops..**.** 
36fb0 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75  ^xMutexInit() mu
36fc0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
36fd0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
36fe0 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
36ff0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
37000 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
37010 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75   ^Similarly, xMu
37020 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
37030 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
37040 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37050 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
37060 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65   mutex.  ^Howeve
37070 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
37080 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
37090 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
370a0 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
370b0 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
370c0 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  x..**.** ^SQLite
370d0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
370e0 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
370f0 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
37100 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
37110 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
37120 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
37130 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
37140 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
37150 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
37160 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
37170 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
37180 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
37190 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
371a0 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
371b0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
371c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
371d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
371e0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
371f0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
37200 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37210 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
37220 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
37230 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
37240 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
37250 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
37260 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
37270 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
37280 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
37290 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
372a0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
372b0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
372c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
372d0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
372e0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
372f0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
37300 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
37310 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
37320 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
37330 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37340 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
37350 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
37360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37370 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
37380 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
37390 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
373a0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
373b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
373c0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
373d0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
373e0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
373f0 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
37400 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c  ments.  ^The SQL
37410 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
37420 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
37430 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
37440 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
37450 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
37460 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
37470 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
37480 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
37490 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72   ^The SQLite cor
374a0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
374b0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
374c0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
374d0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
374e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
374f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
37500 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72  UG flag.  ^Exter
37510 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
37520 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
37530 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
37540 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
37550 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
37560 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
37570 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
37580 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
37590 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
375a0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
375b0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
375c0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
375d0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
375e0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
375f0 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
37600 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
37610 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
37620 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
37630 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
37640 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
37650 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
37660 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
37670 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
37680 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
37690 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
376a0 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
376b0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
376c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
376d0 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
376e0 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
376f0 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
37700 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
37710 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
37720 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
37730 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
37740 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37750 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
37760 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
37770 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37780 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
37790 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
377a0 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73  turn 1.   This s
377b0 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
377c0 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
377d0 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
377e0 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
377f0 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
37800 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
37810 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
37820 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
37830 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
37840 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
37850 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
37860 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
37870 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
37880 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
37890 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
378a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
378b0 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
378c0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
378d0 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
378e0 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
378f0 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  o do.  ^The sqli
37900 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
37910 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
37920 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
37930 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
37940 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37950 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42  .*/.#ifndef NDEB
37960 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  UG.int sqlite3_m
37970 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
37980 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
37990 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
379a0 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
379b0 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ex*);.#endif../*
379c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
379d0 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20  tex Types.**.** 
379e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  The [sqlite3_mut
379f0 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65  ex_alloc()] inte
37a00 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69  rface takes a si
37a10 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
37a20 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66   which is one of
37a30 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
37a40 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
37a50 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69  The set of stati
37a60 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68  c mutexes may ch
37a70 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51  ange from one SQ
37a80 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20  Lite release to 
37a90 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
37aa0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
37ab0 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69  override the bui
37ac0 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69  lt-in mutex logi
37ad0 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65  c must be.** pre
37ae0 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f  pared to accommo
37af0 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  date additional 
37b00 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a  static mutexes..
37b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37b20 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20  E_MUTEX_FAST    
37b30 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
37b40 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37b50 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
37b60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
37b70 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
37b80 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69  ASTER    2.#defi
37b90 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37ba0 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20  STATIC_MEM      
37bb0 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   3  /* sqlite3_m
37bc0 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69  alloc() */.#defi
37bd0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37be0 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20  STATIC_MEM2     
37bf0 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20   4  /* NOT USED 
37c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37c10 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f  E_MUTEX_STATIC_O
37c20 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73  PEN      4  /* s
37c30 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28  qlite3BtreeOpen(
37c40 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37c50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37c60 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
37c70 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
37c80 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37c90 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37ca0 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
37cb0 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
37cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37cd0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
37ce0 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72  U2      7  /* lr
37cf0 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a  u page list */..
37d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37d10 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74  Retrieve the mut
37d20 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ex for a databas
37d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e connection.**.
37d40 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
37d50 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37d60 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65  nter the [sqlite
37d70 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20  3_mutex] object 
37d80 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69  that .** seriali
37d90 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68  zes access to th
37da0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37db0 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e  ection] given in
37dc0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
37dd0 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61   when the [threa
37de0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65  ding mode] is Se
37df0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49 66  rialized..** ^If
37e00 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
37e10 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d  mode] is Single-
37e20 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d  thread or Multi-
37e30 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73  thread then this
37e40 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
37e50 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
37e60 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  er..*/.sqlite3_m
37e70 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62  utex *sqlite3_db
37e80 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29  _mutex(sqlite3*)
37e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37ea0 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
37eb0 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
37ec0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Files.**.** ^Th
37ed0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
37ee0 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
37ef0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
37f00 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
37f10 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
37f20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
37f30 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
37f40 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
37f50 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
37f60 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
37f70 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
37f80 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
37f90 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 6e  ument. ^The.** n
37fa0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
37fb0 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20 74  ase "main" for t
37fc0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
37fd0 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 74   or "temp" for t
37fe0 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 62  he.** TEMP datab
37ff0 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d 65  ase, or the name
38000 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 66   that appears af
38010 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
38020 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  rd for.** databa
38030 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 64  ses that are add
38040 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 54  ed using the [AT
38050 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  TACH] SQL comman
38060 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 6f  d..** ^A NULL po
38070 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 65  inter can be use
38080 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  d in place of "m
38090 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 6f  ain" to refer to
380a0 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 74   the.** main dat
380b0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 5e  abase file..** ^
380c0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
380d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
380e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
380f0 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
38100 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
38110 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
38120 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
38130 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
38140 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
38150 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61    ^The return va
38160 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65  lue of the xFile
38170 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f  Control.** metho
38180 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65  d becomes the re
38190 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
381a0 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
381b0 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
381c0 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e   parameter (zDbN
381d0 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61  ame) does not ma
381e0 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  tch the name of 
381f0 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61  any.** open data
38200 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20  base file, then 
38210 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20  SQLITE_ERROR is 
38220 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69 73  returned.  ^This
38230 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
38240 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64  s not remembered
38250 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
38260 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71   recalled by [sq
38270 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
38280 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
38290 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 20  errmsg()].  The 
382a0 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65  underlying xFile
382b0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d  Control method m
382c0 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74  ight.** also ret
382d0 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  urn SQLITE_ERROR
382e0 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77  .  There is no w
382f0 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73  ay to distinguis
38300 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20  h between.** an 
38310 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d  incorrect zDbNam
38320 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f  e and an SQLITE_
38330 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f  ERROR return fro
38340 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  m the underlying
38350 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
38360 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53   method..**.** S
38370 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
38380 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
38390 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
383a0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71  _file_control(sq
383b0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
383c0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74  ar *zDbName, int
383d0 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   op, void*);../*
383e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
383f0 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 0a  sting Interface.
38400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38410 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
38420 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
38430 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20  sed to read out 
38440 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74  internal.** stat
38450 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20  e of SQLite and 
38460 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73  to inject faults
38470 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72   into SQLite for
38480 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70   testing.** purp
38490 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72 73  oses.  ^The firs
384a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
384b0 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  n operation code
384c0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
384d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20  .** the number, 
384e0 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65  meaning, and ope
384f0 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75  ration of all su
38500 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
38510 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ers..**.** This 
38520 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
38530 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c   for use by appl
38540 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78  ications.  It ex
38550 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66  ists solely.** f
38560 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65  or verifying the
38570 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69   correct operati
38580 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
38590 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e   library.  Depen
385a0 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74  ding.** on how t
385b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
385c0 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74  y is compiled, t
385d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69  his interface mi
385e0 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a  ght not exist..*
385f0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
38600 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f   of the operatio
38610 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d  n codes, their m
38620 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72  eanings, the par
38630 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20  ameters.** they 
38640 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74  take, and what t
38650 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73  hey do are all s
38660 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
38670 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
38680 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20  .** Unlike most 
38690 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50  of the SQLite AP
386a0 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  I, this function
386b0 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
386c0 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65  ed to.** operate
386d0 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72   consistently fr
386e0 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
386f0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69  o the next..*/.i
38700 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  nt sqlite3_test_
38710 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20  control(int op, 
38720 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
38730 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49  I3REF: Testing I
38740 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69  nterface Operati
38750 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
38760 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
38770 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65  re the valid ope
38780 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61  ration code para
38790 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61  meters used.** a
387a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
387b0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
387c0 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _test_control()]
387d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61  ..**.** These pa
387e0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65  rameters and the
387f0 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20  ir meanings are 
38800 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
38810 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74  e.** without not
38820 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75  ice.  These valu
38830 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69  es are for testi
38840 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79  ng purposes only
38850 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
38860 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  s should not use
38870 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61   any of these pa
38880 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a  rameters or the.
38890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74  ** [sqlite3_test
388a0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
388b0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
388c0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54