/ Hex Artifact Content
Login

Artifact 372baf01f7f58b18dfa85e13b55985f2edd6ebc8:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
8580: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  l guarantee that
8590: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
85a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
85b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
85c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
85d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
85e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
85f0: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74  thname().  SQLit
8600: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
8610: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
8620: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
8630: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
8640: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
8650: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
8660: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
8670: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
8680: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
8690: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
86a0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
86b0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
86c0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
86d0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
86e0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
86f0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
8700: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
8710: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
8720: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
8730: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
8740: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
8750: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
8760: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
8770: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
8780: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
8790: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
87a0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
87b0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
87c0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
87d0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
87e0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
87f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8800: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
8810: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
8820: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
8830: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
8840: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
8850: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8860: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
8870: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
8880: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
8890: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
88a0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
88b0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
88c0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
88d0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
88e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
88f0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
8900: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
8910: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
8920: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
8930: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
8940: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
8950: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
8960: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
8970: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
8980: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
8990: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
89a0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
89b0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
89c0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
89d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
89e0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
89f0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
8a00: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8a10: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
8a20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8a30: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
8a40: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
8a50: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
8a60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8a70: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
8a80: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8a90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
8aa0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
8ab0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8ac0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
8ad0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8ae0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
8af0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8b00: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
8b10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
8b20: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
8b30: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
8b40: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
8b50: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
8b60: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
8b70: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
8b80: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
8b90: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
8ba0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
8bb0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
8bc0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
8bd0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
8be0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
8bf0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
8c00: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
8c10: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
8c20: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
8c30: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
8c40: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
8c50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
8c60: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
8c70: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
8c80: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
8c90: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
8ca0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
8cb0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
8cc0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
8cd0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
8ce0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
8cf0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
8d00: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
8d10: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
8d20: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
8d30: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8d40: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8d50: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
8d60: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8d70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8d80: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
8d90: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
8da0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
8db0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
8dc0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8dd0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
8de0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
8df0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
8e00: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
8e10: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  sed.  The [SQLIT
8e20: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8e30: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
8e40: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
8e50: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
8e60: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
8e70: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  urnals..**.** Th
8e80: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
8e90: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
8ea0: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
8eb0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
8ec0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
8ed0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
8ee0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
8ef0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
8f00: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
8f10: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
8f20: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
8f30: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
8f40: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
8f50: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
8f60: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
8f70: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
8f80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8f90: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
8fa0: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
8fb0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
8fc0: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
8fd0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
8fe0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
8ff0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
9000: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
9010: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
9020: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
9030: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
9040: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
9050: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65  ess..**.** At le
9060: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
9070: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
9080: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
9090: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
90a0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
90b0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
90c0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
90d0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
90e0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
90f0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
9100: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
9110: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
9120: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
9130: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
9140: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
9150: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
9160: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
9170: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
9180: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
9190: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
91a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
91b0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
91c0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
91d0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
91e0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
91f0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
9200: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
9210: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
9220: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
9230: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
9240: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
9250: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
9260: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
9270: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
9280: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  call..**.** The 
9290: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
92a0: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
92b0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
92c0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
92d0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
92e0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
92f0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
9300: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
9310: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
9320: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
9330: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
9340: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
9350: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
9360: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
9370: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
9380: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
9390: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
93a0: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
93b0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
93c0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
93d0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
93e0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
93f0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
9400: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
9410: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
9420: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
9430: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
9440: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
9450: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
9460: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
9470: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
9480: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
9490: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
94a0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
94b0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
94c0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
94d0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
94e0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
94f0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
9500: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
9510: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
9520: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
9530: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
9540: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
9550: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
9560: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
9570: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
9580: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
9590: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
95a0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
95b0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
95c0: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
95d0: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
95e0: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
95f0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
9600: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
9610: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
9620: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
9630: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
9640: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
9650: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
9660: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
9670: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
9680: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
9690: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
96a0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
96b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
96c0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
96d0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
96e0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
96f0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
9700: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
9710: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
9720: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
9730: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
9740: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
9750: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
9760: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
9770: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
9780: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
9790: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
97a0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
97b0: 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 78 43  value..** The xC
97c0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
97d0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
97e0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
97f0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9800: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9810: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9820: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9830: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9840: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9850: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9860: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
9870: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9880: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
9890: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
98a0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
98b0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
98c0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
98d0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
98e0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
98f0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9900: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9910: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9920: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9930: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9940: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9950: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9960: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9970: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9980: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
9990: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
99a0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
99b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
99c0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
99d0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
99e0: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
99f0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
9a00: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
9a10: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
9a20: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
9a30: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
9a40: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
9a50: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
9a60: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
9a70: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
9a80: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
9a90: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
9aa0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
9ab0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
9ac0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
9ad0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
9ae0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
9af0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
9b00: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
9b10: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
9b20: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
9b30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9b40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9b50: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
9b60: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
9b70: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
9b80: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
9b90: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
9ba0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9bb0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9bc0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
9bd0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
9be0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9bf0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9c00: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
9c10: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
9c20: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
9c30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9c40: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9c50: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
9c60: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
9c70: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
9c80: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9c90: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
9ca0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
9cb0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
9cc0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
9cd0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
9ce0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
9cf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
9d00: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9d10: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
9d20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
9d30: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9d40: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
9d50: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
9d60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
9d70: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
9d80: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
9d90: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
9da0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
9db0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
9dc0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
9dd0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
9de0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
9df0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
9e00: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
9e10: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
9e20: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
9e30: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
9e40: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
9e50: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
9e60: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
9e70: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
9e80: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
9e90: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
9ea0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
9eb0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
9ec0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
9ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
9ee0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
9ef0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
9f00: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
9f10: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
9f20: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
9f30: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
9f40: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
9f50: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
9f60: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
9f70: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
9f80: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
9f90: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
9fa0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
9fb0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
9fc0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
9fd0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
9fe0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
9ff0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a000: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a010: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a020: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a030: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a040: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a050: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a060: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a070: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a080: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a090: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a0a0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a0b0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a0c0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a0d0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a0e0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a0f0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a100: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a110: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a120: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a130: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a140: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a150: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a160: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a170: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a180: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a190: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a1a0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a1b0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a1c0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a1d0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a1e0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a1f0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a200: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a210: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a220: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a230: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a240: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a250: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a260: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a270: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a280: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a290: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a2a0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a2b0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a2c0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a2d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a2e0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a2f0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a300: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a310: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a320: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a330: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a350: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a370: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a380: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
a390: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
a3a0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
a3b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a3c0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
a3d0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
a3e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
a3f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
a400: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
a410: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a420: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
a430: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
a440: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
a450: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
a460: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
a470: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
a480: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
a490: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
a4a0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
a4b0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
a4c0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
a4d0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
a4e0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a4f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a500: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
a510: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
a520: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a530: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
a540: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
a550: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a560: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
a570: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
a580: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
a590: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
a5a0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
a5b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
a5c0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
a5d0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
a5e0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
a5f0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
a600: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
a610: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
a620: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
a630: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
a640: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
a650: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
a660: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
a670: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
a680: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
a690: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
a6a0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
a6b0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
a6c0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
a6d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a6e0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
a6f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
a700: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
a710: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a720: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
a730: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
a740: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a750: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
a760: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
a770: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
a780: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
a790: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
a7a0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a7b0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
a7c0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
a7d0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
a7e0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
a7f0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
a800: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
a810: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
a820: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
a830: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
a840: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
a850: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
a860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a870: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
a880: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
a890: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
a8a0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
a8b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
a8c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a8d0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
a8e0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
a8f0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
a900: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
a910: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
a920: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
a930: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
a940: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
a950: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a960: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
a970: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
a980: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
a990: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
a9a0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
a9b0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
a9c0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
a9d0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
a9e0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
a9f0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
aa00: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
aa10: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
aa20: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
aa30: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
aa40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
aa50: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
aa60: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
aa70: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
aa80: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
aa90: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
aaa0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
aab0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
aac0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
aad0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
aae0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
aaf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ab00: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
ab10: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
ab20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ab30: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
ab40: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
ab50: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
ab60: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
ab70: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
ab80: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
ab90: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
aba0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
abb0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
abc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
abd0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
abe0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
abf0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ac00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ac10: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
ac20: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
ac30: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
ac40: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
ac50: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
ac60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
ac70: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
ac80: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
ac90: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
aca0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
acb0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
acc0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
acd0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ace0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
acf0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
ad00: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
ad10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
ad20: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
ad30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ad40: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
ad50: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
ad60: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
ad70: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
ad80: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
ad90: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
ada0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
adb0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
adc0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
add0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
ade0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
adf0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
ae00: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
ae10: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
ae20: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
ae30: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
ae40: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
ae50: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
ae60: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
ae70: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
ae80: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
ae90: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
aea0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
aeb0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
aec0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
aed0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
aee0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
aef0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
af00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
af10: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
af20: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
af30: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
af40: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
af50: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
af60: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
af70: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
af80: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
af90: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
afa0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
afb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afd0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
afe0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
aff0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b000: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b010: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b020: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b030: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b040: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b050: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b060: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b070: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b080: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b090: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b0a0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b0b0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b0c0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b0d0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b0e0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b0f0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b100: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b110: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b120: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b130: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b140: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b150: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b160: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b170: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b180: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b190: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b1a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b1b0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b1c0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b1d0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b1e0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b1f0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b200: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b210: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b220: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b230: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b240: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b250: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b260: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b270: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b280: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b290: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b2a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b2b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b2c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b2d0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b2e0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b2f0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b300: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b310: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b320: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b330: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b340: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b350: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b360: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b370: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b380: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
b390: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
b3a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b3b0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
b3c0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
b3d0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
b3e0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
b3f0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
b400: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
b410: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
b420: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
b430: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
b440: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
b450: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
b460: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
b470: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
b480: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
b490: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
b4a0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
b4b0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
b4c0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
b4d0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
b4e0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
b4f0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
b500: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
b510: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
b520: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
b530: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
b540: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b550: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
b560: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
b570: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
b580: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
b590: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
b5a0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
b5b0: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
b5c0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
b5d0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
b5e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b5f0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
b600: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
b610: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b620: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
b630: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
b640: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
b650: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
b660: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
b670: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
b680: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
b690: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
b6a0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
b6b0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
b6c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
b6d0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
b6e0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
b6f0: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
b700: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
b710: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
b720: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
b730: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
b740: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
b750: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
b760: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
b770: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
b780: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
b790: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
b7a0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
b7b0: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
b7c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b7d0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
b7e0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
b7f0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
b800: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
b810: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
b820: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
b830: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
b840: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b850: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
b860: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
b870: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
b880: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
b890: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
b8a0: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
b8b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b8c0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
b8d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
b8e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
b8f0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
b900: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
b910: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
b920: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
b930: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
b940: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
b950: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
b960: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
b970: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
b980: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
b990: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
b9a0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
b9b0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
b9c0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
b9d0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
b9e0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
b9f0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
ba00: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
ba10: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
ba20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
ba30: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
ba40: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
ba50: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
ba60: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
ba70: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
ba80: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
ba90: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
baa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bab0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
bac0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
bad0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
bae0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
baf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
bb00: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
bb10: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
bb20: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
bb30: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
bb40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
bb50: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
bb60: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
bb70: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
bb80: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
bb90: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
bba0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
bbb0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
bbc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bbd0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
bbe0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
bbf0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
bc00: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
bc10: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
bc20: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
bc30: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
bc40: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
bc50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
bc60: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
bc70: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
bc80: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
bc90: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
bca0: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
bcb0: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
bcc0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
bcd0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
bce0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
bcf0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
bd00: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
bd10: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bd20: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
bd30: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
bd40: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
bd50: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
bd60: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
bd70: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
bd80: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
bd90: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
bda0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
bdb0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
bdc0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
bdd0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
bde0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
bdf0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
be00: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
be10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
be20: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
be30: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
be40: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
be50: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
be60: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
be70: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
be80: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
be90: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
bea0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
beb0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
bec0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
bed0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
bee0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
bef0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
bf00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
bf10: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
bf20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
bf30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
bf40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bf50: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
bf60: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
bf70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
bf80: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
bf90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
bfa0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
bfb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
bfc0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
bfd0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
bfe0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
bff0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c000: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c010: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c020: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c030: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c040: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c050: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c060: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c070: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c080: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c090: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c0a0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c0b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c0c0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c0d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c0e0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c0f0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c100: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c110: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c120: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c130: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c140: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c150: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c160: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c170: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c180: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c190: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c1a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c1b0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c1c0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c1d0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c1e0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c1f0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c200: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c210: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c220: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c230: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c240: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c250: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c260: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c270: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c280: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c290: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c2a0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c2b0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c2c0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c2d0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c2e0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c2f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c300: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c310: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c320: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c330: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c340: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c350: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c360: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c370: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c380: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
c390: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
c3a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c3b0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
c3c0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
c3d0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
c3e0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
c3f0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
c400: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c410: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
c420: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
c430: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
c440: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
c450: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
c460: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
c470: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c480: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
c490: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c4a0: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
c4b0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
c4c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c4d0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
c4e0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
c4f0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
c500: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c510: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
c520: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
c530: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
c540: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
c550: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
c560: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
c570: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
c580: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
c590: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
c5a0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
c5b0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
c5c0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
c5d0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
c5e0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
c5f0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
c600: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
c610: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
c620: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
c630: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c640: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
c650: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
c660: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
c670: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
c680: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
c690: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
c6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c6b0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
c6c0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
c6d0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
c6e0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
c6f0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
c700: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
c710: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
c720: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
c730: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
c740: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
c750: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
c760: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
c770: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
c780: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
c790: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
c7a0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
c7b0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
c7c0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
c7d0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
c7e0: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
c7f0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
c800: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
c810: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
c820: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
c830: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
c840: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
c850: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
c860: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
c870: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
c880: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
c890: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c8a0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
c8b0: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
c8c0: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
c8d0: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
c8e0: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
c8f0: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
c900: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
c910: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c920: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c930: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
c940: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
c950: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
c960: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
c970: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
c980: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
c990: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
c9a0: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
c9b0: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
c9c0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
c9d0: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
c9e0: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
c9f0: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
ca00: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
ca10: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
ca20: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
ca30: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
ca40: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
ca50: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
ca60: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
ca70: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
ca80: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
ca90: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
caa0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
cab0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cac0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
cad0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
cae0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
caf0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
cb00: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
cb10: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
cb20: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
cb30: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
cb40: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
cb50: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
cb60: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
cb70: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
cb80: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
cb90: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
cba0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
cbb0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
cbc0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
cbd0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
cbe0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
cbf0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
cc00: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
cc10: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
cc20: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
cc30: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
cc40: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
cc50: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
cc60: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
cc70: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
cc80: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
cc90: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
cca0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
ccb0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
ccc0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
ccd0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
cce0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
ccf0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
cd00: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
cd10: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
cd20: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
cd30: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
cd40: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
cd50: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
cd60: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
cd70: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
cd80: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
cd90: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
cda0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
cdb0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
cdc0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
cdd0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
cde0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
cdf0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
ce00: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
ce10: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
ce20: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
ce30: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
ce40: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
ce50: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
ce60: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
ce70: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
ce80: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
ce90: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
cea0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
ceb0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
cec0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
ced0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
cee0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
cef0: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
cf00: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
cf10: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
cf20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
cf30: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
cf40: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
cf50: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
cf60: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
cf70: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
cf80: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
cf90: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
cfa0: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
cfb0: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
cfc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
cfd0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
cfe0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
cff0: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d000: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d010: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d020: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d030: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d040: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d050: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d060: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d070: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d080: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d090: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d0a0: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d0b0: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d0c0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d0d0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d0e0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d0f0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d100: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d110: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d120: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d130: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d140: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d150: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d160: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d170: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d180: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d190: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d1a0: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d1b0: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d1c0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d1d0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d1e0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d1f0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d200: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d210: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d220: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d230: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d240: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d250: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d260: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d270: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d280: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d290: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d2a0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d2b0: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d2c0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d2d0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d2e0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d2f0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d300: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d310: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d320: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d330: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d340: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d350: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d360: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d370: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d380: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
d390: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d3a0: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
d3b0: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
d3c0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
d3d0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d3e0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
d3f0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
d400: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
d410: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
d420: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
d430: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d440: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
d450: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
d460: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d470: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d480: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
d490: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
d4a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d4b0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
d4c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d4d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
d4e0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
d4f0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d500: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
d510: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
d520: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
d530: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
d540: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
d550: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
d560: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
d570: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
d580: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
d590: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d5a0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
d5b0: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
d5c0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
d5d0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
d5e0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
d5f0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d600: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
d610: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
d620: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d630: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
d640: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
d650: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
d660: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
d670: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
d680: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
d690: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
d6a0: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
d6b0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d6c0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
d6d0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
d6e0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
d6f0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
d700: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
d710: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
d720: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
d730: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d740: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
d750: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
d760: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
d770: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
d780: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
d790: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
d7a0: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
d7b0: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
d7c0: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
d7d0: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
d7e0: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
d7f0: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
d800: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
d810: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
d820: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d830: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
d840: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
d850: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
d860: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
d870: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d880: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d890: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
d8a0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d8b0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d8c0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d8d0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d8e0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d8f0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
d900: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
d910: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
d920: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
d930: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d940: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d950: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d960: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
d970: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
d980: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
d990: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
d9a0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
d9b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d9c0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
d9d0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
d9e0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
d9f0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
da00: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
da10: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
da20: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
da30: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
da40: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
da50: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
da60: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
da70: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
da80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
da90: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
daa0: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
dab0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
dac0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
dad0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
dae0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
daf0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
db00: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
db10: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
db20: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
db30: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
db40: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
db50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
db60: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
db70: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
db80: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
db90: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
dba0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
dbb0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dbc0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
dbd0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dbe0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
dbf0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
dc00: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
dc10: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
dc20: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
dc30: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
dc40: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
dc50: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
dc60: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
dc70: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
dc80: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
dc90: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
dca0: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
dcb0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
dcc0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
dcd0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
dce0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
dcf0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
dd00: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
dd10: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
dd20: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
dd30: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
dd40: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
dd50: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
dd60: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
dd70: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
dd80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
dd90: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
dda0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
ddb0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
ddc0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
ddd0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
dde0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ddf0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
de00: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
de10: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
de20: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
de30: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
de40: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
de50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
de60: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
de70: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
de80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
de90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
dea0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
deb0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
dec0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
ded0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
dee0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
def0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
df00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
df10: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
df20: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
df30: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
df40: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
df50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
df60: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
df70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
df80: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
df90: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
dfa0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dfb0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dfc0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dfd0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dfe0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dff0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e000: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e010: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e020: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e030: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e040: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e050: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e060: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e070: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e080: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e090: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e0a0: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e0b0: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e0c0: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e0d0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e0e0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e0f0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e100: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e110: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e120: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e130: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e140: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e150: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e160: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e170: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e180: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e190: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e1a0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e1b0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e1c0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e1d0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e1e0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e1f0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e200: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e210: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e220: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e230: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e240: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e250: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e260: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e270: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e280: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e290: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e2a0: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e2b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e2c0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e2d0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e2e0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e2f0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e300: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e310: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e320: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e330: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e340: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e350: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e360: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e370: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e380: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
e390: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
e3a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e3b0: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
e3c0: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
e3d0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e3e0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
e3f0: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
e400: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
e410: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
e420: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
e430: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
e440: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
e450: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
e460: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
e470: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
e480: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e490: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
e4a0: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
e4b0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
e4c0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
e4d0: 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
e4e0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
e4f0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
e500: 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
e510: 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
e520: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
e530: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
e540: 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
e550: 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
e560: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
e570: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
e580: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
e590: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
e5a0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e5b0: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
e5c0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
e5d0: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
e5e0: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
e5f0: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
e600: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
e610: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
e620: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
e630: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
e640: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
e650: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
e660: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
e670: 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c  ch the scrach al
e680: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
e690: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
e6a0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
e6b0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
e6c0: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
e6d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e6e0: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
e6f0: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
e700: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
e710: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
e720: 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a  le of 16. The sz
e730: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
e740: 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73  d be a few bytes
e750: 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20  .** larger than 
e760: 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74  the actual scrat
e770: 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ch space require
e780: 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61  d due to interna
e790: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54  l overhead..** T
e7a0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e7b0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
e7c0: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
e7d0: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
e7e0: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
e7f0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
e800: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
e810: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
e820: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
e830: 68 20 62 75 66 66 65 72 20 70 65 72 20 74 68 72  h buffer per thr
e840: 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
e850: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
e860: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
e870: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
e880: 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20  reads.  ^SQLite 
e890: 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65  will.** never re
e8a0: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
e8b0: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
e8c0: 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73  ore than 6 times
e8d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
e8e0: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
e8f0: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
e900: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63  ds additional sc
e910: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
e920: 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20  ond .** what is 
e930: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
e940: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e950: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
e960: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
e970: 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
e980: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
e990: 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64  mory needed.</dd
e9a0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e9b0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
e9c0: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
e9d0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
e9e0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
e9f0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
ea00: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
ea10: 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
ea20: 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
ea30: 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
ea40: 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
ea50: 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a  plemenation.  .*
ea60: 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
ea70: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
ea80: 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
ea90: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
eaa0: 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
eab0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
eac0: 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
ead0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
eae0: 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a  PCACHE option..*
eaf0: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
eb00: 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
eb10: 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
eb20: 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
eb30: 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
eb40: 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
eb50: 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
eb60: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
eb70: 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
eb80: 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
eb90: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
eba0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
ebb0: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
ebc0: 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
ebd0: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
ebe0: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
ebf0: 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
ec00: 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
ec10: 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
ec20: 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
ec30: 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
ec40: 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
ec50: 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
ec60: 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
ec70: 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
ec80: 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
ec90: 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
eca0: 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
ecb0: 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
ecc0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
ecd0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
ece0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
ecf0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
ed00: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
ed10: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
ed20: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
ed30: 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
ed40: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ed50: 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
ed60: 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
ed70: 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
ed80: 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
ed90: 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
eda0: 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
edb0: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
edc0: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
edd0: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
ede0: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
edf0: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
ee00: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
ee10: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ee20: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
ee30: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
ee40: 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65  e..** ^The imple
ee50: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
ee60: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
ee70: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
ee80: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
ee90: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
eea0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
eeb0: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
eec0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
eed0: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
eee0: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
eef0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
ef00: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
ef10: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
ef20: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
ef30: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ef40: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
ef50: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ef60: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
ef70: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
ef80: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
ef90: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
efa0: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
efb0: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
efc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
efd0: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
efe0: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
eff0: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
f000: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
f010: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
f020: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
f030: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
f040: 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
f050: 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
f060: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
f070: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
f080: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
f090: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
f0a0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
f0b0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
f0c0: 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
f0d0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
f0e0: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
f0f0: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
f100: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
f110: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
f120: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f130: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
f140: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
f150: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
f160: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
f170: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
f180: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f190: 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
f1a0: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
f1b0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
f1c0: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
f1d0: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
f1e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
f1f0: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
f200: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
f210: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
f220: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
f230: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
f240: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
f250: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
f260: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
f270: 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
f280: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
f290: 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
f2a0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
f2b0: 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
f2c0: 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
f2d0: 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
f2e0: 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
f2f0: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
f300: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f310: 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
f320: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f330: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
f340: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
f350: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
f360: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
f370: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f380: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
f390: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
f3a0: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
f3b0: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
f3c0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
f3d0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
f3e0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
f3f0: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
f400: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
f410: 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
f420: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
f430: 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
f440: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
f450: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
f460: 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
f470: 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
f480: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f490: 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
f4a0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f4b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
f4c0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f4d0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
f4e0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
f4f0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
f500: 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
f510: 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
f520: 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
f530: 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
f540: 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
f550: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f560: 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
f570: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
f580: 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
f590: 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
f5a0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
f5b0: 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
f5c0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f5d0: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
f5e0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f5f0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
f600: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f610: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
f620: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
f630: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
f640: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f650: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
f660: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
f670: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
f680: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
f690: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
f6a0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
f6b0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
f6c0: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
f6d0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
f6e0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
f6f0: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
f700: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
f710: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
f720: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
f730: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
f740: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
f750: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
f760: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
f770: 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
f780: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
f790: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
f7a0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
f7b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
f7c0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f7d0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
f7e0: 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
f7f0: 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
f800: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
f810: 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
f820: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
f830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
f840: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
f850: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
f860: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f870: 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
f880: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
f890: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
f8a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
f8b0: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
f8c0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
f8d0: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
f8e0: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
f8f0: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
f900: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
f910: 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
f920: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
f930: 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
f940: 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
f950: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
f960: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f970: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
f980: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
f990: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
f9a0: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
f9b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
f9c0: 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
f9d0: 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
f9e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
f9f0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
fa00: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
fa10: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
fa20: 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
fa30: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
fa40: 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
fa50: 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
fa60: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
fa70: 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
fa80: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
fa90: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
faa0: 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
fab0: 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
fac0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
fad0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
fae0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
faf0: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
fb00: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
fb10: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
fb20: 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
fb30: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
fb40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
fb50: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
fb60: 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
fb70: 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
fb80: 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
fb90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
fba0: 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
fbb0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
fbc0: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
fbd0: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
fbe0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
fbf0: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
fc00: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
fc10: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c  ONFIG_GETPCACHE<
fc20: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
fc30: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
fc40: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
fc50: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
fc60: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
fc70: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
fc80: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
fc90: 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
fca0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
fcb0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
fcc0: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
fcd0: 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
fce0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
fcf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
fd00: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
fd10: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
fd20: 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
fd30: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
fd40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
fd50: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
fd60: 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
fd70: 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
fd80: 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
fd90: 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
fda0: 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
fdb0: 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
fdc0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
fdd0: 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
fde0: 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
fdf0: 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
fe00: 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
fe10: 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
fe20: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
fe30: 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
fe40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
fe50: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
fe60: 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
fe70: 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
fe80: 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
fe90: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
fea0: 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
feb0: 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
fec0: 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
fed0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
fee0: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
fef0: 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
ff00: 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
ff10: 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
ff20: 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
ff30: 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
ff40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
ff50: 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
ff60: 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
ff70: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
ff80: 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
ff90: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
ffa0: 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
ffb0: 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
ffc0: 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
ffd0: 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
ffe0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fff0: 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
10000 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
10010 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
10020 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
10030 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
10040 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
10050 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
10060 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
10070 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
10080 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
10090 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
100a0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
100b0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
100c0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
100d0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
100e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
100f0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
10100 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
10110 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
10120 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
10130 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
10140 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
10150 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
10160 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10170 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10180 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
10190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
101a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
101b0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
101c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
101d0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
101e0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
101f0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
10200 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10210 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
10220 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10230 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
10240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10250 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
10260 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10270 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
10290 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
102a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
102b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
102c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
102d0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
102e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
102f0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
10300 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10310 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
10320 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
10330 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
10340 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10350 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
10360 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
10370 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
10380 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10390 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
103a0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
103b0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
103c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
103d0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
103e0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
103f0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
10400 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
10410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
10420 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
10430 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
10440 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
10450 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
10460 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
10470 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
10480 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
10490 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
104a0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
104b0 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  e_methods* */.#d
104c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
104d0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
104e0 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   15  /* sqlite3_
104f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
10500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10510 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
10520 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
10530 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a  nc, void* */../*
10540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
10550 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
10560 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
10570 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
10580 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
10590 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
105a0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
105b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
105c0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
105d0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
105e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
105f0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
10600 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10610 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
10620 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10630 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
10640 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
10650 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
10660 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
10670 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10680 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
10690 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
106a0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
106b0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
106c0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
106d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
106e0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
106f0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
10700 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
10710 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10720 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
10730 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
10740 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10750 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
10760 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
10770 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
10780 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
10790 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
107a0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
107b0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
107c0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
107d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
107e0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
107f0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
10800 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
10810 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
10820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10830 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
10840 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
10850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
10860 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
10870 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
10880 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
10890 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
108a0 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
108b0 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72  nter to an memor
108c0 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
108d0 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
108e0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
108f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
10900 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
10910 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10920 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
10930 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
10940 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
10950 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
10960 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
10970 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
10980 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
10990 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
109a0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
109b0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
109c0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
109d0 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
109e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
109f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
10a00 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
10a10 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
10a20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10a30 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
10a40 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
10a50 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
10a60 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
10a70 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
10a80 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
10a90 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
10aa0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
10ab0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
10ac0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10ad0 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
10ae0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10af0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
10b00 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
10b10 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
10b20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
10b30 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
10b40 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  .** multiple of 
10b50 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  8.  See also: [S
10b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10b70 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a  KASIDE]</dd>.**.
10b80 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
10b90 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
10ba0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
10bb0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
10bc0 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
10bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
10be0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
10bf0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
10c00 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
10c10 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
10c20 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
10c30 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
10c40 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
10c50 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
10c60 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
10c70 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
10c80 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
10c90 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
10ca0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
10cb0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
10cc0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
10cd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10ce0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
10cf0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
10d00 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
10d10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
10d20 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
10d30 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
10d40 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
10d50 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
10d60 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
10d70 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
10d80 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
10d90 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
10da0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
10db0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
10dc0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
10dd0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
10de0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
10df0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
10e00 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
10e10 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
10e20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
10e30 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
10e40 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
10e50 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
10e60 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
10e70 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
10e80 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
10e90 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
10ea0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
10eb0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
10ec0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
10ed0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
10ee0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
10ef0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
10f00 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
10f10 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
10f20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10f30 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10f40 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  st argument.  ^I
10f50 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
10f60 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
10f70 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
10f80 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
10f90 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
10fa0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
10fb0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
10fc0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
10fd0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
10fe0 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
10ff0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
11000 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
11010 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
11020 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
11030 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
11040 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
11050 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
11060 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
11070 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
11080 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
11090 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
110a0 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
110b0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
110c0 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a  igger fired.)^.*
110d0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
110e0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
110f0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
11100 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
11110 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
11120 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
11130 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
11140 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
11150 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
11160 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
11170 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
11180 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
11190 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
111a0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
111b0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
111c0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
111d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
111e0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
111f0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
11200 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
11210 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
11220 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
11230 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
11240 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
11250 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
11260 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
11270 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
11280 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
11290 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
112a0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
112b0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
112c0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
112d0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
112e0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
112f0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
11300 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
11310 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
11320 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
11330 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
11340 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
11350 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
11360 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
11370 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
11380 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
11390 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
113a0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
113b0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
113c0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
113d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
113e0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
113f0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
11400 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
11410 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
11420 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
11430 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
11440 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
11450 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
11460 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
11470 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
11480 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
11490 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
114a0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
114b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
114c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
114d0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
114e0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
114f0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
11500 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
11510 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
11520 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
11530 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
11540 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
11550 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
11560 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
11570 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
11580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11590 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
115a0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
115b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
115c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
115d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
115e0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
115f0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
11600 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
11610 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
11620 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
11630 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
11640 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
11650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11660 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
11670 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11680 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
11690 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
116a0 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
116b0 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
116c0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
116d0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
116e0 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
116f0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
11700 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
11710 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
11720 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
11730 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
11740 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
11750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
11760 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
11770 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
11780 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
11790 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
117a0 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
117b0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
117c0 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
117d0 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
117e0 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
117f0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
11800 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
11810 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
11820 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
11830 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
11840 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
11850 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
11860 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
11870 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
11880 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
11890 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
118a0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
118b0 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
118c0 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
118d0 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
118e0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
118f0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
11900 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
11910 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
11920 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
11930 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
11940 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
11950 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
11960 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
11970 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
11980 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11990 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
119a0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
119b0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
119c0 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
119d0 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
119e0 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
119f0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
11a00 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
11a10 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
11a20 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
11a30 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
11a40 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
11a50 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
11a60 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
11a70 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
11a80 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
11a90 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
11aa0 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
11ab0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
11ac0 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
11ad0 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
11ae0 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
11af0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
11b00 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
11b10 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
11b20 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
11b30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
11b40 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
11b50 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
11b60 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
11b70 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
11b80 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11b90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
11ba0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
11bb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
11bc0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
11bd0 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
11be0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
11bf0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
11c00 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
11c10 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
11c20 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
11c30 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
11c40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
11c50 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
11c60 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11c70 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
11c80 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
11c90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
11ca0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
11cb0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
11cc0 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
11cd0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
11ce0 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
11cf0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
11d00 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
11d10 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
11d20 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
11d30 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
11d40 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
11d50 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
11d60 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
11d70 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11d80 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
11d90 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
11da0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
11db0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
11dc0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
11dd0 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
11de0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
11df0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
11e00 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
11e10 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
11e20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
11e30 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
11e40 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
11e50 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
11e60 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
11e70 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
11e80 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
11e90 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
11ea0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
11eb0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
11ec0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11ed0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11ee0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11ef0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
11f00 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11f10 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
11f20 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
11f30 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
11f40 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
11f50 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
11f60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
11f70 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
11f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11f90 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
11fa0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
11fb0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
11fc0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
11fd0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
11fe0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
11ff0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
12000 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
12010 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
12020 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
12030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
12040 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
12050 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
12060 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
12070 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
12080 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
12090 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
120a0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
120b0 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
120c0 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
120d0 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
120e0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
120f0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
12100 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
12110 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
12120 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
12130 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
12140 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
12150 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
12160 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
12170 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
12180 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
12190 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
121a0 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
121b0 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
121c0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
121d0 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
121e0 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
121f0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
12200 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
12210 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
12220 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
12230 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
12240 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
12250 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
12260 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
12270 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
12280 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
12290 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
122a0 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
122b0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
122c0 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
122d0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
122e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
122f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
12300 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
12310 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
12320 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
12330 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
12340 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
12350 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
12360 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
12370 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
12380 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
12390 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
123a0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
123b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
123c0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
123d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
123e0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
123f0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
12400 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
12410 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
12420 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
12430 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
12440 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
12450 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
12470 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
12480 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
12490 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
124a0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
124b0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
124c0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
124d0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
124e0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
124f0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
12500 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
12510 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
12520 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
12530 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
12540 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
12550 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
12560 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
12570 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
12580 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
12590 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
125a0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
125b0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
125c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
125d0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
125e0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
125f0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
12600 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
12610 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
12620 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
12630 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
12640 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
12650 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
12660 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12670 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
12680 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
12690 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
126a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
126b0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
126c0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
126d0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
126e0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
126f0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
12700 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12710 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
12720 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
12730 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
12740 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
12750 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
12760 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
12770 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
12780 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
12790 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
127a0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
127b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
127c0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
127d0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
127e0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
127f0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
12800 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
12810 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
12820 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12830 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12840 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
12850 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
12860 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
12870 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
12880 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
12890 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
128a0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
128b0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
128c0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
128d0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
128e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
128f0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
12900 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
12910 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
12920 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12930 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12940 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
12950 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
12960 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
12970 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
12980 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
12990 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
129a0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
129b0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
129c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
129d0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
129e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
129f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
12a00 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
12a10 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
12a20 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
12a30 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
12a40 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
12a50 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
12a60 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
12a70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12a80 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
12a90 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
12aa0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
12ab0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
12ac0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
12ad0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
12ae0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12af0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12b00 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
12b10 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
12b20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
12b30 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
12b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
12b50 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
12b60 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
12b70 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12b80 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
12b90 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
12ba0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
12bb0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
12bc0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12bd0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
12be0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
12bf0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
12c00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
12c10 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
12c20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
12c30 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
12c40 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
12c50 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
12c60 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
12c70 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
12c80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
12c90 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
12ca0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
12cb0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
12cc0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
12cd0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
12ce0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
12cf0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
12d00 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
12d10 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
12d20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
12d30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
12d40 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
12d50 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
12d60 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
12d70 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
12d80 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
12d90 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
12da0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
12db0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
12dc0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
12dd0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
12de0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
12df0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
12e00 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
12e10 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
12e20 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
12e30 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
12e40 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
12e50 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
12e60 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
12e70 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
12e80 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
12e90 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
12ea0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
12eb0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
12ec0 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
12ed0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
12ee0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
12ef0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
12f00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
12f10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
12f20 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
12f30 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
12f40 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
12f50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12f60 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
12f70 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
12f80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
12f90 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
12fa0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
12fb0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
12fc0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
12fd0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
12fe0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
12ff0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
13000 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
13010 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
13020 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13030 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
13040 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
13050 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
13060 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
13070 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
13080 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
13090 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
130a0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
130b0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
130c0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
130d0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
130e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
130f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13100 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
13110 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
13120 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
13130 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
13140 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
13150 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
13160 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
13170 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
13180 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
13190 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
131a0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
131b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
131c0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
131d0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
131e0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
131f0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
13200 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
13210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
13220 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
13230 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
13240 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
13250 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
13260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13270 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
13280 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
13290 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
132a0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
132b0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
132c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
132d0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
132e0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
132f0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
13300 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
13310 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
13320 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
13330 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
13340 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
13350 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
13360 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
13370 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
13380 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
13390 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
133a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
133b0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
133c0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
133d0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
133e0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
133f0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
13400 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
13410 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
13420 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
13430 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
13440 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13450 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13460 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
13470 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
13480 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
13490 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
134a0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
134b0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
134c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
134d0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
134e0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
134f0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13500 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
13510 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
13520 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
13530 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
13540 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
13550 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
13560 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
13570 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
13580 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
13590 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
135a0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
135b0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
135c0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
135d0 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
135e0 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
135f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13600 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13610 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
13620 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
13630 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
13640 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
13650 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
13660 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
13670 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
13680 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
13690 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
136a0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
136b0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
136c0 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
136d0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
136e0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
136f0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
13700 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
13710 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
13720 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
13730 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
13740 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
13750 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
13760 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13770 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
13780 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
13790 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
137a0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
137b0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
137c0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
137d0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
137e0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
137f0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
13800 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
13810 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
13820 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13830 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
13840 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
13850 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
13860 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
13870 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
13880 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
13890 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
138a0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
138b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
138c0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
138d0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
138e0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
138f0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13900 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
13910 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
13920 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
13930 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
13940 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
13950 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
13960 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
13970 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
13980 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
13990 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
139a0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
139b0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
139c0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
139d0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
139e0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
139f0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
13a00 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
13a10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
13a20 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
13a30 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
13a40 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
13a50 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
13a60 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
13a70 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13a80 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
13a90 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
13aa0 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
13ab0 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
13ac0 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
13ad0 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
13ae0 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
13af0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
13b00 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
13b10 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
13b20 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
13b30 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
13b40 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
13b50 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
13b60 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
13b70 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
13b80 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
13b90 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
13ba0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
13bb0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
13bc0 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
13bd0 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
13be0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
13bf0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
13c00 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
13c10 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
13c20 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
13c30 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
13c40 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
13c50 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
13c60 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
13c70 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
13c80 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
13c90 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
13ca0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13cb0 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
13cc0 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
13cd0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
13ce0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
13cf0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
13d00 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
13d10 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
13d20 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
13d30 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13d40 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
13d50 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13d60 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
13d70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
13d80 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
13d90 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
13da0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
13db0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
13dc0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
13dd0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
13de0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
13df0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
13e00 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
13e10 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
13e20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
13e30 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
13e40 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
13e50 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
13e60 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
13e70 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
13e80 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
13e90 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
13ea0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
13eb0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
13ec0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
13ed0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
13ee0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
13ef0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
13f00 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
13f10 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
13f20 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
13f30 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
13f40 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
13f50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
13f60 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
13f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13f80 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
13f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13fa0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
13fb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
13fc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13fd0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
13fe0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
13ff0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
14000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14010 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
14020 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
14030 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
14040 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
14050 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
14060 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
14070 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
14080 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
14090 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
140a0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
140b0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
140c0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
140d0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
140e0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
140f0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
14100 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
14110 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
14120 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
14130 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
14140 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
14150 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
14160 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
14170 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
14180 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
14190 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
141a0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
141b0 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
141c0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
141d0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
141e0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
141f0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
14200 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
14210 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
14220 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
14230 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
14240 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
14250 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
14260 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14270 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
14280 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
14290 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
142a0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
142b0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
142c0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
142d0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
142e0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
142f0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
14300 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
14310 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
14320 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
14330 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
14340 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
14350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
14360 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
14370 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
14380 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65  Queries.**.** De
14390 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
143a0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
143b0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
143c0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
143d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
143e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
143f0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
14400 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
14410 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
14420 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
14430 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
14440 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
14450 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
14460 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
14470 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
14480 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
14490 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
144a0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
144b0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
144c0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
144d0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
144e0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
144f0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
14500 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
14510 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
14520 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
14530 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
14540 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
14550 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
14560 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
14570 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
14580 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
14590 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
145a0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
145b0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
145c0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
145d0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
145e0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
145f0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
14600 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
14610 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
14620 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
14630 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
14640 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
14650 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
14660 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
14670 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
14680 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
14690 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
146a0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
146b0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
146c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
146d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
146e0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
146f0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
14700 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
14710 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
14720 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
14730 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
14740 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
14750 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
14760 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
14770 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
14780 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
14790 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
147a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
147b0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
147c0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
147d0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
147e0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
147f0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
14800 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
14810 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
14820 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
14830 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
14840 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
14850 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14860 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
14870 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
14880 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
14890 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
148a0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
148b0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
148c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
148d0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
148e0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
148f0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
14900 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
14910 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
14920 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
14930 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
14940 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
14950 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
14960 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
14970 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
14980 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
14990 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
149a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
149b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
149c0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
149d0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
149e0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
149f0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
14a00 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
14a10 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
14a20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14a30 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
14a40 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14a50 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
14a60 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14a70 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
14a80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14a90 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
14aa0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
14ab0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
14ac0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
14ad0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14af0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14b00 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
14b10 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
14b20 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
14b30 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
14b40 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
14b50 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
14b60 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
14b70 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
14b80 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
14b90 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
14ba0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
14bb0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
14bc0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
14bd0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
14be0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
14bf0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
14c00 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
14c10 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
14c20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74  it should pass t
14c30 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14c40 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
14c50 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
14c60 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
14c70 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
14c80 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
14c90 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
14ca0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
14cb0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14cc0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
14cd0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
14ce0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
14cf0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
14d00 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
14d10 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
14d20 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
14d30 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
14d40 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
14d50 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
14d60 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
14d70 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
14d80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
14d90 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14da0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
14db0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
14dc0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
14dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
14de0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
14df0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
14e00 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
14e10 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
14e20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
14e30 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
14e40 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
14e50 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
14e60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
14e70 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
14e80 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
14e90 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
14ea0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
14eb0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
14ec0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
14ed0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14ee0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
14ef0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
14f00 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
14f10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
14f20 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
14f30 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
14f40 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
14f50 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
14f60 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
14f70 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
14f80 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
14f90 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
14fa0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
14fb0 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
14fc0 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
14fd0 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
14fe0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
14ff0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
15000 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
15010 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
15020 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
15030 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
15040 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
15050 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
15060 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
15070 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
15080 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
15090 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
150a0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
150b0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
150c0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
150d0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
150e0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
150f0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
15100 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
15110 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
15120 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
15130 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
15140 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
15150 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
15160 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
15170 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
15180 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
15190 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
151a0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
151b0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
151c0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
151d0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
151e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
151f0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
15200 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
15210 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
15220 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
15230 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
15240 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
15250 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
15260 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
15270 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
15280 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
15290 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
152a0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
152b0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
152c0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
152d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing..**.** ^(In 
152e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
152f0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
15300 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
15310 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
15320 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
15330 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
15340 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
15350 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
15360 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
15370 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15380 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
15390 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
153a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
153b0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
153c0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
153d0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
153e0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
153f0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
15400 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
15410 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
15420 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
15430 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
15440 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
15450 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15460 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
15470 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
15480 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
15490 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
154a0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
154b0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
154c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
154d0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
154e0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
154f0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
15500 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
15510 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
15520 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
15530 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
15540 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
15550 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
15560 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
15570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
15580 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15590 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
155a0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
155b0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
155c0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
155d0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
155e0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
155f0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15600 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
15610 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
15620 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
15630 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
15640 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
15650 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
15660 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
15670 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
15680 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
15690 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
156a0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
156b0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
156c0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
156d0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
156e0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
156f0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
15700 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
15710 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
15720 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
15730 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
15740 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
15750 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
15760 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
15770 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
15780 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
15790 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
157a0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
157b0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
157c0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
157d0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
157e0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
157f0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
15800 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
15810 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
15820 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
15830 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
15840 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
15850 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
15860 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
15870 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
15880 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
15890 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
158a0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
158b0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
158c0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
158d0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
158e0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
158f0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
15900 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
15910 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
15920 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
15930 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
15940 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
15950 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
15960 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
15970 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15980 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
15990 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
159a0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
159b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
159c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
159d0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
159e0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
159f0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
15a00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15a10 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
15a20 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
15a30 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
15a40 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
15a50 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
15a60 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
15a70 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
15a80 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
15a90 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
15aa0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
15ab0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15ac0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
15ad0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
15ae0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
15af0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
15b00 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
15b10 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
15b20 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
15b30 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
15b40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15b50 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
15b60 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
15b70 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
15b80 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15b90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15ba0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
15bb0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
15bc0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
15bd0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
15be0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
15bf0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
15c00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15c10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
15c20 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15c30 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
15c40 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
15c50 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
15c60 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
15c70 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
15c80 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
15c90 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
15ca0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
15cb0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
15cc0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
15cd0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
15ce0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
15cf0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
15d00 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
15d10 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
15d20 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
15d30 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
15d40 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
15d50 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
15d60 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
15d70 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
15d80 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
15d90 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
15da0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
15db0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
15dc0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
15dd0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
15de0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
15df0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
15e00 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
15e10 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
15e20 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15e30 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
15e40 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15e50 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
15e60 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
15e70 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
15e80 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
15e90 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
15ea0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
15eb0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
15ec0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15ed0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
15ee0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
15ef0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
15f00 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
15f10 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
15f20 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
15f30 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
15f40 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15f50 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
15f60 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
15f70 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
15f80 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
15f90 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
15fa0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
15fb0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
15fc0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
15fd0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
15fe0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
15ff0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
16000 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
16010 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
16020 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
16030 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
16040 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
16050 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
16060 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
16070 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
16080 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16090 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
160a0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
160b0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
160c0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
160d0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
160e0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
160f0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
16100 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
16110 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
16120 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
16130 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
16140 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
16150 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
16160 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
16170 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
16180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
16190 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
161a0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
161b0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
161c0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
161d0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
161e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
161f0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
16200 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
16210 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
16220 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
16230 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
16240 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
16250 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
16260 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
16270 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
16280 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
16290 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
162a0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
162b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
162c0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
162d0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
162e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
162f0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
16300 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
16310 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
16320 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
16330 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
16340 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
16350 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
16360 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
16370 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
16380 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16390 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
163a0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
163b0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
163c0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
163d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
163e0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
163f0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
16400 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
16410 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
16420 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
16430 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
16440 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
16450 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
16460 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
16470 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
16480 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
16490 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
164a0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
164b0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
164c0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
164d0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
164e0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
164f0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
16500 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
16510 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
16520 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
16530 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
16540 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
16550 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
16560 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
16570 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
16580 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
16590 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
165a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
165b0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
165c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
165d0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
165e0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
165f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
16600 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
16610 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16620 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
16630 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
16640 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
16650 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16660 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
16670 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
16680 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
16690 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
166a0 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
166b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
166c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
166d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
166e0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
166f0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
16700 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
16710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
16720 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
16730 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16740 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
16750 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
16760 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16770 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16780 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
16790 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
167a0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
167b0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
167c0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
167d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
167e0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
167f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
16810 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
16820 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
16830 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
16840 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
16850 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
16860 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
16870 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
16880 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
16890 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
168a0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
168b0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
168c0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
168d0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
168e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
168f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16900 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
16910 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
16920 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
16930 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
16940 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
16950 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16960 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
16970 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
16980 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
16990 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
169a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
169b0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
169c0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
169d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
169e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
169f0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
16a00 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
16a10 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
16a20 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
16a30 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  oundary..**.** I
16a40 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
16a50 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
16a60 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
16a70 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
16a80 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
16a90 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
16aa0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
16ab0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
16ac0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
16ad0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
16ae0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
16af0 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
16b00 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
16b10 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
16b20 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
16b30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
16b40 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
16b50 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
16b60 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
16b70 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
16b80 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
16b90 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
16ba0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
16bb0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
16bc0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
16bd0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
16be0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
16bf0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
16c00 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
16c10 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
16c20 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
16c30 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
16c40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16c50 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
16c60 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
16c70 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
16c80 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
16c90 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
16ca0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
16cb0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
16cc0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
16cd0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
16ce0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
16cf0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
16d00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16d10 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
16d20 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
16d30 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
16d40 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
16d50 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
16d60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16d70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
16d80 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
16d90 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
16da0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
16db0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
16dc0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
16dd0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
16de0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
16df0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
16e00 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
16e10 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
16e20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16e30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
16e40 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
16e50 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
16e60 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
16e70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
16e80 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
16e90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
16ea0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
16eb0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
16ec0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
16ed0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
16ee0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
16ef0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
16f00 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
16f10 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
16f20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
16f30 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
16f40 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
16f50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16f60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
16f70 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
16f80 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
16f90 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
16fa0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
16fb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16fc0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
16fd0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16fe0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
16ff0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
17000 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
17010 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
17020 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
17030 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
17040 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
17050 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
17060 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
17070 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
17080 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
17090 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
170a0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
170b0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
170c0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
170d0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
170e0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
170f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17100 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
17110 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
17120 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
17130 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
17140 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
17150 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17160 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
17170 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
17180 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
17190 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
171a0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
171b0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
171c0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
171d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
171e0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
171f0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
17200 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
17210 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
17220 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
17230 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
17240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
17250 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17260 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
17270 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
17280 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
17290 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
172a0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
172b0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
172c0 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
172d0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
172e0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
172f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17300 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
17310 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
17320 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
17330 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
17340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17350 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
17360 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
17370 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
17380 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
17390 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
173a0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
173b0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
173c0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
173d0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
173e0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
173f0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
17400 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
17410 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
17420 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
17430 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
17440 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
17450 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
17460 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
17470 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
17480 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
17490 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
174a0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
174b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
174c0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
174d0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
174e0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
174f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
17500 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
17510 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
17520 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
17530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
17540 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
17550 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
17560 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
17570 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
17580 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
17590 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
175a0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
175b0 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
175c0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
175d0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
175e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
175f0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
17600 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
17610 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
17620 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
17630 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
17640 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
17650 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
17660 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
17670 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
17680 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
17690 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
176a0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
176b0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
176c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
176d0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
176e0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
176f0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
17700 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
17710 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
17720 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
17730 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
17740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17750 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
17760 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
17770 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
17780 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17790 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
177a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
177b0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
177c0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
177d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
177e0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
177f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17800 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
17810 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
17820 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17830 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
17840 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
17850 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
17860 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
17870 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
17880 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
17890 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
178a0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
178b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
178c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
178d0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
178e0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
178f0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
17900 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
17910 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
17920 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
17930 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
17940 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17950 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
17960 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
17970 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
17980 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17990 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
179a0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
179b0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
179c0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
179d0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
179e0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
179f0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
17a00 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
17a10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17a20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
17a30 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
17a40 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
17a50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
17a60 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
17a70 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
17a80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17a90 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17aa0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
17ab0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
17ac0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
17ad0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
17ae0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
17af0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
17b00 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
17b10 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
17b20 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17b30 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
17b40 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
17b50 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17b60 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
17b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17b80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
17b90 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
17ba0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
17bb0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17bc0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17bd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17be0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17bf0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17c00 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
17c10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17c20 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17c30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17c40 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
17c50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
17c60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
17c70 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
17c80 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
17c90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
17ca0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
17cb0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
17cc0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17cd0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17ce0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
17cf0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
17d00 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17d10 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
17d20 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
17d30 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
17d40 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
17d50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17d60 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
17d70 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
17d80 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
17d90 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
17da0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
17db0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
17dc0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
17dd0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
17de0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
17df0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
17e00 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
17e10 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
17e20 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
17e30 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
17e40 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
17e50 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
17e60 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
17e70 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
17e80 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
17e90 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
17ea0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
17eb0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
17ec0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
17ed0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
17ee0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
17ef0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
17f00 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
17f10 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
17f20 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
17f30 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
17f40 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
17f50 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
17f60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
17f70 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17f80 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
17f90 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
17fa0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
17fb0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
17fc0 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
17fd0 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
17fe0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
17ff0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
18000 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
18010 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
18020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
18030 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
18040 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
18050 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
18060 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
18070 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
18080 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
18090 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
180a0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
180b0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
180c0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
180d0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
180e0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
180f0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
18100 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
18110 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
18120 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
18130 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
18140 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
18150 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
18160 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
18170 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
18180 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
18190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
181a0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
181b0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
181c0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
181d0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
181e0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
181f0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
18200 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
18210 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
18220 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
18230 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
18240 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
18250 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
18260 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
18270 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
18280 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
18290 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
182a0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
182b0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
182c0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
182d0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
182e0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
182f0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
18300 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
18310 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
18320 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
18330 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
18340 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
18350 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
18360 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
18370 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
18380 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
18390 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
183a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
183b0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
183c0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
183d0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
183e0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
183f0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
18400 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
18410 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
18420 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
18430 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
18440 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
18450 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
18460 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
18470 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18480 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
18490 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
184a0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
184b0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
184c0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
184d0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
184e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
184f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
18500 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18510 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
18520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18530 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
18540 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
18550 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
18560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18570 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
18580 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
18590 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
185a0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
185b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
185c0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
185d0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
185e0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
185f0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
18600 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
18610 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
18620 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
18630 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
18640 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
18650 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
18660 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
18670 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
18680 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
18690 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
186a0 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
186b0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
186c0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
186d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
186e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
186f0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
18700 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18710 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
18720 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
18730 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
18740 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
18750 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
18760 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
18770 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
18780 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
18790 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
187a0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
187b0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
187c0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
187d0 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
187e0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
187f0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
18800 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
18810 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18820 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18830 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18840 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
18850 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18860 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18870 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
18880 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
18890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
188a0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
188b0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
188c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
188d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
188e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
188f0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
18900 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
18910 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
18920 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
18930 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
18940 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
18950 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
18960 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
18970 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
18980 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
18990 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
189a0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
189b0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
189c0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
189d0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
189e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
189f0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
18a00 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
18a10 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
18a20 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
18a30 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
18a40 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
18a50 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
18a60 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
18a70 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
18a80 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
18a90 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
18aa0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
18ab0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18ac0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
18ad0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
18ae0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
18af0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
18b00 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
18b10 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
18b20 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
18b30 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
18b40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
18b50 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18b60 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
18b70 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
18b80 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
18b90 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
18ba0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
18bb0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
18bc0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
18bd0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18be0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
18bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
18c00 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
18c10 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
18c20 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
18c30 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
18c40 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
18c50 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
18c60 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
18c70 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
18c80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
18c90 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18ca0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18cb0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
18cc0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
18cd0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
18ce0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
18cf0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
18d00 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18d10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18d20 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18d30 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18d40 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18d50 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
18d60 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
18d70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
18d80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18d90 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
18da0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
18db0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
18dc0 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
18dd0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
18de0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
18df0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
18e00 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
18e10 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
18e20 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
18e30 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
18e40 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
18e50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18e60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
18e70 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
18e80 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
18e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18ea0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
18eb0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
18ec0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18ed0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18ef0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
18f00 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
18f10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18f20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18f40 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
18f50 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
18f60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18f70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18f80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18f90 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
18fa0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
18fb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18fc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18fd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18fe0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
18ff0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
19000 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19010 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19030 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
19040 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19050 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
19080 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
19090 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
190a0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
190b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
190c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
190d0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
190e0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
190f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19110 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
19120 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
19130 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19160 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
19170 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
19180 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19190 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
191a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
191b0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
191c0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
191d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
191e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
191f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19200 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
19210 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
19220 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
19230 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
19260 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
19270 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19280 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
192a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
192b0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
192c0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
192d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
192e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
192f0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
19300 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
19310 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19320 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19340 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
19350 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
19360 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19370 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19390 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
193a0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
193b0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
193c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
193d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
193e0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
193f0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
19400 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19420 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
19430 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
19440 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
19450 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
19460 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
19470 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
19480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19490 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
194a0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
194b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
194c0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
194d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
194e0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
194f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19500 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19510 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
19520 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
19530 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
19540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19560 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
19570 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
19580 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19590 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
195a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
195b0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
195c0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
195d0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
195e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
195f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19600 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
19610 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
19620 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
19630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19650 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
19660 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
19670 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
19680 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
196a0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
196b0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
196c0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
196d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
196e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
196f0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
19700 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
19710 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19740 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
19750 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
19760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
19770 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19790 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
197a0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
197b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
197c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
197d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
197e0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
197f0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
19800 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
19810 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
19820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19830 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
19840 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
19850 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
19860 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
19870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19880 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
19890 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
198a0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
198b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
198c0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
198d0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
198e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
198f0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
19900 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
19910 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
19920 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
19930 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
19940 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
19950 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
19960 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
19970 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19980 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19990 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
199a0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
199b0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
199c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
199d0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
199e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
199f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19a00 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
19a10 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
19a20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19a30 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
19a40 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19a50 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19a60 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19a70 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
19a80 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
19a90 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19aa0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
19ab0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19ac0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
19ad0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
19ae0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
19af0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
19b00 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
19b10 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
19b20 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19b30 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
19b40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19b50 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19b60 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19b70 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19b80 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
19b90 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
19ba0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19bb0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19bc0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19bd0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19be0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19bf0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19c00 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
19c10 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
19c20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
19c30 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19c40 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
19c50 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
19c60 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
19c70 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
19c80 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
19c90 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
19ca0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
19cb0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
19cc0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
19cd0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
19ce0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
19cf0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
19d00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
19d10 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
19d20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
19d30 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
19d40 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
19d50 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
19d60 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
19d70 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
19d80 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
19d90 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
19da0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
19db0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
19dc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
19dd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
19de0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
19df0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
19e00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
19e10 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
19e20 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
19e30 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
19e40 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
19e50 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
19e60 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
19e70 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
19e80 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
19e90 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
19ea0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
19eb0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
19ec0 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
19ed0 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
19ee0 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
19ef0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19f00 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
19f10 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
19f20 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
19f30 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
19f40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
19f50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
19f60 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
19f70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
19f80 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
19f90 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
19fa0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
19fb0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
19fc0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
19fd0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  query..**.** ^If
19fe0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19ff0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1a000 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1a010 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1a020 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1a030 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1a040 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1a050 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1a060 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1a070 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1a080 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1a090 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1a0a0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1a0b0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1a0c0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1a0d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a0e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1a0f0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a100 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1a110 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a120 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1a130 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1a140 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1a150 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a160 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1a170 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1a180 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1a190 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
1a1a0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1a1b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1a1c0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1a1d0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1a1e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a1f0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1a200 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1a210 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1a220 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1a230 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1a240 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
1a250 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
1a260 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1a270 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1a280 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1a290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1a2a0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1a2b0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1a2c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a2d0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1a2e0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1a2f0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1a300 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1a310 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1a320 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1a330 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1a340 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1a350 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1a360 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1a370 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1a380 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1a390 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1a3a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1a3b0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1a3c0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1a3d0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1a3e0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1a3f0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1a400 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1a410 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1a420 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1a430 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1a440 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1a450 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1a460 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1a470 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1a480 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1a490 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1a4a0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1a4b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1a4c0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1a4d0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1a4e0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1a4f0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1a500 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1a510 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1a520 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1a530 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1a540 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1a550 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1a560 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1a570 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1a580 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1a590 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1a5a0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1a5b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1a5c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a5d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1a5e0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1a5f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1a600 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1a610 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1a620 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1a630 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1a640 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1a650 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1a660 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1a670 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1a680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a690 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1a6a0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1a6b0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1a6c0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1a6d0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1a6e0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1a6f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a700 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1a710 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1a720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1a730 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1a740 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1a750 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1a760 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1a770 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1a780 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1a790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1a7a0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1a7b0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1a7c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1a7d0 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1a7e0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1a7f0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1a800 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1a810 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1a820 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a830 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1a840 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1a850 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1a860 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f  DCACHE],.** and/
1a870 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1a880 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1a890 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1a8a0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1a8b0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1a8c0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1a8d0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a8e0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1a8f0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1a900 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1a910 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1a920 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1a930 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1a940 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1a950 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1a960 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1a970 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a980 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1a990 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1a9a0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1a9b0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1a9c0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1a9d0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1a9e0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1a9f0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1aa00 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1aa10 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1aa20 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1aa30 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1aa40 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1aa50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1aa60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1aa70 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1aa80 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1aa90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1aaa0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1aab0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1aac0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1aad0 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a   creates it if.*
1aae0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1aaf0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1ab00 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1ab10 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1ab20 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1ab30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ab40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ab50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1ab60 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1ab70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1ab80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ab90 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1aba0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1abb0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1abc0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
1abd0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1abe0 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
1abf0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
1ac00 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1ac10 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1ac20 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b  FULLMUTEX],.** [
1ac30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1ac40 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20  EDCACHE] and/or 
1ac50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1ac60 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  REDCACHE] flags,
1ac70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1ac80 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1ac90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1aca0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1acb0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1acc0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1acd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ace0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1acf0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1ad00 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1ad10 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1ad20 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1ad30 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1ad40 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1ad50 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1ad60 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
1ad70 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1ad80 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
1ad90 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
1ada0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1adb0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
1adc0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1add0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
1ade0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
1adf0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
1ae00 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
1ae10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1ae20 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
1ae30 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
1ae40 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
1ae50 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1ae60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ae70 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
1ae80 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
1ae90 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
1aea0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1aeb0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1aec0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1aed0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
1aee0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1aef0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
1af00 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
1af10 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1af20 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1af30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1af40 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
1af50 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
1af60 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1af70 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
1af80 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
1af90 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1afa0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1afb0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1afc0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1afd0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1afe0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1aff0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1b000 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1b010 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1b020 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1b030 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b040 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1b050 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1b060 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1b070 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1b080 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1b090 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1b0a0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1b0b0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1b0c0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1b0d0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1b0e0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1b0f0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1b100 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1b110 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1b120 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1b130 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1b140 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1b150 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1b160 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1b170 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1b180 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1b190 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1b1a0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1b1b0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1b1c0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1b1d0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1b1e0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1b1f0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1b200 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1b210 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1b220 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1b230 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1b240 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  sed..**.** ^The 
1b250 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1b260 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1b270 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1b280 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1b290 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1b2a0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1b2b0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1b2c0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1b2d0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1b2e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b2f0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1b300 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1b310 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1b320 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1b330 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1b340 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1b350 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1b360 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1b370 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1b380 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1b390 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1b3a0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1b3b0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1b3c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1b3d0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1b3e0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1b3f0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1b400 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1b410 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1b420 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1b430 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1b440 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1b450 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1b460 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1b470 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1b480 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1b490 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1b4a0 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  2()..*/.int sqli
1b4b0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1b4c0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1b4d0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1b4e0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1b4f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1b500 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1b510 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1b520 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1b530 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1b540 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1b550 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1b560 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1b570 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1b580 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1b590 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1b5a0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1b5b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1b5c0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1b5d0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1b5e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1b5f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1b600 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1b610 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1b620 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1b630 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1b640 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1b650 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1b660 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1b670 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1b680 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1b690 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1b6a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1b6b0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1b6c0 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
1b6d0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1b6e0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1b6f0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1b700 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1b710 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1b720 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1b730 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1b740 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1b750 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1b760 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1b770 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b780 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1b790 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1b7a0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1b7b0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1b7c0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1b7d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1b7e0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1b7f0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1b800 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
1b810 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1b820 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
1b830 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
1b840 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1b850 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
1b860 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
1b870 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
1b880 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
1b890 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
1b8a0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
1b8b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b8c0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1b8d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1b8e0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1b8f0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1b900 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1b910 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1b920 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1b930 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1b940 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
1b950 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1b960 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1b970 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1b980 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1b990 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1b9a0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1b9b0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1b9c0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1b9d0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1b9e0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1b9f0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1ba00 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1ba10 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1ba20 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1ba30 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1ba40 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
1ba50 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1ba60 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1ba70 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1ba80 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1ba90 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1baa0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1bab0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1bac0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1bad0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1bae0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1baf0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1bb00 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1bb10 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1bb20 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1bb30 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1bb40 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1bb50 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1bb60 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1bb70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1bb80 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1bb90 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1bba0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1bbb0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1bbc0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1bbd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bbe0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1bbf0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1bc00 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1bc10 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1bc20 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1bc30 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1bc40 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1bc50 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1bc60 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1bc70 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1bc80 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1bc90 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1bca0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1bcb0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1bcc0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1bcd0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1bce0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1bcf0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1bd00 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1bd10 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1bd20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1bd30 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1bd40 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1bd50 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1bd60 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1bd70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1bd80 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1bd90 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
1bda0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1bdb0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1bdc0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1bdd0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1bde0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1bdf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1be00 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1be10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1be20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1be30 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1be40 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1be50 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1be60 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1be70 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1be80 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1be90 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1bea0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1beb0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1bec0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1bed0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1bee0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1bef0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1bf00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1bf10 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1bf20 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1bf30 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1bf40 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1bf50 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1bf60 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1bf70 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1bf80 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1bf90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1bfa0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1bfb0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1bfc0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1bfd0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1bfe0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1bff0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1c000 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1c010 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1c020 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1c030 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1c040 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1c050 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1c060 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1c070 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1c080 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c090 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1c0a0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1c0b0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1c0c0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1c0d0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1c0e0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1c0f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c100 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1c110 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1c120 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1c130 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1c140 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1c150 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1c160 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1c170 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1c180 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1c190 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1c1a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1c1b0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
1c1c0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
1c1d0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1c1e0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1c1f0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1c200 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1c210 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1c220 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1c230 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1c240 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1c250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c260 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1c270 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1c280 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1c290 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1c2a0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1c2b0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1c2c0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1c2d0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1c2e0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1c2f0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1c300 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1c310 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1c320 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1c330 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1c340 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c350 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e  the old limit.)^
1c360 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
1c370 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
1c380 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
1c390 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
1c3a0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
1c3b0 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  the limit catego
1c3c0 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d  ry of SQLITE_LIM
1c3d0 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20  IT_XYZ there is 
1c3e0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
1c3f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1c400 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f  ].** set by a co
1c410 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1c420 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1c430 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74  named .** [limit
1c440 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  s | SQLITE_MAX_X
1c450 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  YZ]..** (The "_L
1c460 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1c470 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1c480 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
1c490 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
1c4a0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1c4b0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1c4c0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1c4d0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1c4e0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1c4f0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
1c500 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
1c510 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1c520 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1c530 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1c540 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1c550 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1c560 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1c570 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1c580 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1c590 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1c5a0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1c5b0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1c5c0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1c5d0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
1c5e0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1c5f0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1c600 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1c610 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1c620 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1c630 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1c640 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1c650 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1c660 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1c670 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1c680 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1c690 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1c6a0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1c6b0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1c6c0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1c6d0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1c6e0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1c6f0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1c700 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1c710 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1c720 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1c730 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1c740 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1c750 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1c760 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1c770 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1c780 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1c790 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1c7a0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1c7b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1c7c0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1c7d0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1c7e0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1c7f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1c800 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1c810 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1c820 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1c830 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1c840 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1c850 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
1c860 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1c870 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1c880 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1c890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c8a0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1c8b0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
1c8c0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1c8d0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
1c8e0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1c8f0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1c900 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1c910 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
1c920 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
1c930 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
1c940 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
1c950 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1c960 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
1c970 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
1c980 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
1c990 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
1c9a0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
1c9b0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1c9c0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
1c9d0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
1c9e0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
1c9f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1ca00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1ca10 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1ca20 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
1ca30 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
1ca40 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
1ca50 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a  le row.<dd>)^.**
1ca60 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1ca70 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1ca80 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1ca90 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1caa0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1cab0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
1cac0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1cad0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1cae0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
1caf0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1cb00 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1cb10 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
1cb20 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
1cb30 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
1cb40 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
1cb50 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1cb60 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1cb70 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
1cb80 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
1cb90 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
1cba0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
1cbb0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1cbc0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
1cbd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1cbe0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
1cbf0 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
1cc00 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
1cc10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1cc20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1cc30 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1cc40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1cc50 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1cc60 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
1cc70 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
1cc80 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
1cc90 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1cca0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1ccb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ccc0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1ccd0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
1cce0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
1ccf0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
1cd00 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1cd10 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
1cd20 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1cd30 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1cd40 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1cd50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1cd60 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1cd70 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1cd80 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1cd90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1cda0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1cdb0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1cdc0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cdd0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1cde0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1cdf0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1ce00 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1ce10 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1ce20 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1ce30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1ce40 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1ce50 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1ce60 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1ce70 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1ce80 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1ce90 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cea0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1ceb0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1cec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1ced0 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1cee0 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1cef0 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1cf00 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1cf10 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1cf20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1cf30 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
1cf40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1cf50 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
1cf60 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
1cf70 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
1cf80 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1cf90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1cfa0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1cfb0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1cfc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1cfd0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1cfe0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1cff0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1d000 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1d010 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1d020 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1d030 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1d040 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1d050 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d060 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1d070 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1d080 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d090 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1d0a0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1d0b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d0c0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1d0d0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1d0e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d0f0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1d100 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1d110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d120 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1d130 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1d140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d150 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1d160 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1d170 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d180 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1d190 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1d1a0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1d1b0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1d1c0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
1d1d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1d1e0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1d1f0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1d200 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1d210 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1d220 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1d230 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1d240 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1d250 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1d260 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1d270 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1d280 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1d290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d2a0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1d2b0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
1d2c0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1d2d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1d2e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1d2f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1d300 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
1d310 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d320 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
1d330 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
1d340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1d350 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
1d360 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
1d370 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1d380 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1d390 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1d3a0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1d3b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1d3c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1d3d0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1d3e0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
1d3f0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
1d400 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1d410 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d420 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1d430 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
1d440 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1d450 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1d460 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1d470 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1d480 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1d490 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
1d4a0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1d4b0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1d4c0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1d4d0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1d4e0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1d4f0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
1d500 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1d510 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
1d520 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
1d530 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
1d540 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
1d550 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
1d560 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
1d570 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
1d580 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
1d590 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
1d5a0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
1d5b0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
1d5c0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
1d5d0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
1d5e0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
1d5f0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
1d600 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
1d610 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
1d620 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
1d630 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
1d640 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1d650 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1d660 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
1d670 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
1d680 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
1d690 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
1d6a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
1d6b0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1d6c0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1d6d0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
1d6e0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1d6f0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1d700 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1d710 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1d720 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
1d730 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
1d740 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1d750 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1d760 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
1d770 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
1d780 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
1d790 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1d7a0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1d7b0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1d7c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1d7d0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1d7e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1d7f0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
1d800 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1d810 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1d820 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1d830 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
1d840 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1d850 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1d860 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
1d870 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1d880 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1d890 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1d8a0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
1d8b0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1d8c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1d8d0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1d8e0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1d8f0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1d900 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1d910 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1d920 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1d930 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
1d940 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1d950 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
1d960 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d970 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
1d980 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1d990 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
1d9a0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1d9b0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1d9c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1d9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d9e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1d9f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1da00 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1da10 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1da20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1da30 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1da40 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1da50 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1da60 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1da70 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1da80 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1da90 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
1daa0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1dab0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1dac0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1dad0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1dae0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1daf0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1db00 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1db10 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1db20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1db30 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1db40 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1db50 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
1db60 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
1db70 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
1db80 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
1db90 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1dba0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1dbb0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1dbc0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1dbd0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1dbe0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1dbf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dc00 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1dc10 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1dc20 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1dc30 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1dc40 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49  un it again.  ^I
1dc50 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1dc60 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1dc70 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1dc80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1dc90 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1dca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1dcb0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1dcc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1dcd0 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1dce0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1dcf0 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1dd00 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1dd10 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1dd20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1dd30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1dd40 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1dd50 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1dd60 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1dd70 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1dd80 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1dd90 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1dda0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1ddb0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1ddc0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1ddd0 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1dde0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1ddf0 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1de00 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1de10 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1de20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1de30 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1de40 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1de50 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1de60 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1de70 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1de80 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1de90 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1dea0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1deb0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1dec0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1ded0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
1dee0 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
1def0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1df00 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1df10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
1df20 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
1df30 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1df40 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1df50 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1df60 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1df70 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1df80 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1df90 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1dfa0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1dfb0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1dfc0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1dfd0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ^If the value of
1dfe0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20   a [parameter | 
1dff0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
1e000 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  in the WHERE cla
1e010 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61  use might.** cha
1e020 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70 6c  nge the query pl
1e030 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
1e040 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61  nt, then the sta
1e050 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a  tement may be.**
1e060 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1e070 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66  ecompiled (as if
1e080 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
1e090 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29  a schema change)
1e0a0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a   on the first .*
1e0b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1e0c0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
1e0d0 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20  g any change to 
1e0e0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1e0f0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
1e100 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70  dings] of the [p
1e110 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c  arameter]. .** <
1e120 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
1e130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1e140 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
1e150 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1e160 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1e170 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1e180 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1e190 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1e1a0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1e1b0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1e1c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1e1d0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1e1e0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1e1f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1e200 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e210 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e220 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e230 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1e240 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e250 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e260 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e270 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e280 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1e290 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1e2a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1e2b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1e2c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1e2d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1e2e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1e2f0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1e300 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1e310 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1e320 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1e330 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1e340 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1e350 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1e360 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1e370 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1e380 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1e390 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1e3a0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1e3b0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1e3c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1e3d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1e3e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1e3f0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1e400 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1e410 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1e420 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1e430 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1e440 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1e450 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1e460 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1e470 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1e480 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1e490 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1e4a0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1e4b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1e4c0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1e4d0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1e4e0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1e4f0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1e500 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1e510 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1e520 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e530 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1e540 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e550 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1e560 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1e570 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1e580 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1e590 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1e5a0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1e5b0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1e5c0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1e5d0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1e5e0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1e5f0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1e600 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1e610 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1e620 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1e630 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1e640 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1e650 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
1e660 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
1e670 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
1e680 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
1e690 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1e6a0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1e6b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1e6c0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1e6d0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1e6e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e6f0 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
1e700 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
1e710 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1e720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e730 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1e740 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e750 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
1e760 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1e770 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1e780 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e790 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1e7a0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1e7b0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1e7c0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1e7d0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1e7e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e7f0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1e800 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1e810 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e820 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1e830 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1e840 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1e850 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1e860 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1e870 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1e880 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1e890 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
1e8a0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1e8b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e8c0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1e8d0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1e8e0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1e8f0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1e900 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1e910 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1e920 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1e930 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1e940 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1e950 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1e960 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1e970 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1e980 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1e990 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1e9a0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1e9b0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1e9c0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1e9d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1e9e0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1e9f0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1ea00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1ea10 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1ea20 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1ea30 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1ea40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1ea50 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1ea60 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1ea70 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1ea80 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1ea90 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1eaa0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1eab0 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1eac0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1ead0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1eae0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1eaf0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1eb00 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1eb10 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1eb20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1eb30 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1eb40 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1eb50 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1eb60 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1eb70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1eb80 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1eb90 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1eba0 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1ebb0 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1ebc0 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1ebd0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1ebe0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1ebf0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1ec00 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1ec10 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1ec20 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1ec30 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1ec40 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1ec50 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1ec60 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1ec70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1ec80 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1ec90 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1eca0 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1ecb0 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1ecc0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1ecd0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1ece0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1ecf0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1ed00 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1ed10 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1ed20 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1ed30 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1ed40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ed50 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1ed60 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1ed70 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
1ed80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ed90 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
1eda0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
1edb0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
1edc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1edd0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
1ede0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1edf0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
1ee00 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
1ee10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ee20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
1ee30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1ee40 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
1ee50 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
1ee60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ee70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1ee80 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
1ee90 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
1eea0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
1eeb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
1eec0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
1eed0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
1eee0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
1eef0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
1ef00 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
1ef10 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1ef20 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1ef30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ef40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1ef50 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
1ef60 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
1ef70 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
1ef80 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1ef90 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
1efa0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1efb0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1efc0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1efd0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1efe0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1eff0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
1f000 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
1f010 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
1f020 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
1f030 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
1f040 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1f050 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
1f060 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1f070 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1f080 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
1f090 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
1f0a0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
1f0b0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
1f0c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1f0d0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
1f0e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
1f0f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
1f100 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
1f110 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
1f120 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
1f130 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
1f140 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
1f150 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1f160 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
1f170 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1f180 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
1f190 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1f1a0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
1f1b0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
1f1c0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
1f1d0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1f1e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1f1f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1f200 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1f210 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1f220 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1f230 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1f240 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1f250 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1f260 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1f270 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1f280 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
1f290 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
1f2a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1f2b0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1f2c0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
1f2d0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
1f2e0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
1f2f0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
1f300 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
1f310 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
1f320 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
1f330 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
1f340 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
1f350 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
1f360 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
1f370 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
1f380 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
1f390 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
1f3a0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
1f3b0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
1f3c0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
1f3d0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
1f3e0 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29  eric identifer.)
1f3f0 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
1f400 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
1f410 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
1f420 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
1f430 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
1f440 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
1f450 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
1f460 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1f470 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1f480 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
1f490 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1f4a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1f4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1f4c0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
1f4d0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
1f4e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1f4f0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
1f500 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
1f510 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f520 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1f530 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
1f540 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1f550 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
1f560 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
1f570 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
1f580 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
1f590 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
1f5a0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
1f5b0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
1f5c0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
1f5d0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
1f5e0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
1f5f0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
1f600 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
1f610 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
1f620 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
1f630 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1f640 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
1f650 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1f660 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1f670 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1f680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f690 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1f6a0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1f6b0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
1f6c0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1f6d0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1f6e0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1f6f0 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
1f700 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1f710 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
1f720 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
1f730 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
1f740 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1f750 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
1f760 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
1f770 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
1f780 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
1f790 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
1f7a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1f7b0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
1f7c0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
1f7d0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
1f7e0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
1f7f0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1f800 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1f810 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
1f820 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
1f830 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1f840 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
1f850 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
1f860 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
1f870 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
1f880 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
1f890 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1f8a0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
1f8b0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
1f8c0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
1f8d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1f8e0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1f8f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1f900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
1f910 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1f920 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1f930 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1f940 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1f950 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1f960 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1f970 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1f980 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1f990 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1f9a0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1f9b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1f9c0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
1f9d0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
1f9e0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
1f9f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
1fa00 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
1fa10 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
1fa20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
1fa30 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
1fa40 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
1fa50 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1fa60 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
1fa70 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1fa80 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
1fa90 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
1faa0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
1fab0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
1fac0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1fad0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
1fae0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
1faf0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
1fb00 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
1fb10 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
1fb20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1fb30 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
1fb40 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
1fb50 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
1fb60 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
1fb70 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
1fb80 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
1fb90 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
1fba0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
1fbb0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
1fbc0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
1fbd0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
1fbe0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
1fbf0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
1fc00 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
1fc10 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1fc20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
1fc30 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
1fc40 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
1fc50 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1fc60 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
1fc70 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
1fc80 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
1fc90 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
1fca0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1fcb0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1fcc0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1fcd0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
1fce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1fcf0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1fd00 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1fd10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
1fd20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1fd30 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
1fd40 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
1fd50 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
1fd60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1fd70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
1fd80 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
1fd90 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
1fda0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
1fdb0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
1fdc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
1fdd0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
1fde0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
1fdf0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
1fe00 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
1fe10 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1fe20 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
1fe30 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
1fe40 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
1fe50 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
1fe60 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
1fe70 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
1fe80 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
1fe90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
1fea0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
1feb0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
1fec0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
1fed0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
1fee0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1fef0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
1ff00 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
1ff10 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
1ff20 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
1ff30 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
1ff40 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
1ff50 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1ff60 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1ff70 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1ff80 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1ff90 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
1ffa0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1ffb0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1ffc0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1ffd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ffe0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1fff0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
20000 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
20010 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
20020 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20030 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
20040 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20050 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
20060 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
20070 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
20080 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
20090 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
200a0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
200b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
200c0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
200d0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
200e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
200f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20100 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
20110 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
20120 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
20130 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
20140 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
20150 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
20160 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
20170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20180 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
20190 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
201a0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
201b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
201c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
201d0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
201e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
201f0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
20200 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
20210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20220 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
20230 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
20240 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
20250 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
20260 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
20270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20280 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
20290 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
202a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
202b0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
202c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
202d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
202e0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
202f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
20300 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
20310 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
20320 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
20330 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
20340 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
20350 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
20360 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
20370 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
20380 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20390 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
203a0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
203b0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
203c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
203d0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
203e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
203f0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
20400 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
20410 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
20420 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
20430 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
20440 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
20450 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
20460 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
20470 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
20480 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
20490 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
204a0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
204b0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
204c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
204d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
204e0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
204f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20500 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20510 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
20520 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20530 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
20540 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20550 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20560 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
20570 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
20580 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
20590 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
205a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
205b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
205c0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
205d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
205e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
205f0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
20600 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
20610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20620 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
20630 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
20640 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
20650 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
20660 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
20670 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
20680 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
20690 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
206a0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
206b0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
206c0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
206d0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
206e0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
206f0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
20700 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
20710 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
20720 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
20730 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
20740 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
20750 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
20760 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
20770 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
20780 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
20790 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
207a0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
207b0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
207c0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
207d0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
207e0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
207f0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
20800 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
20810 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
20820 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
20830 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
20840 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
20850 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
20860 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
20870 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
20880 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
20890 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
208a0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
208b0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
208c0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
208d0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
208e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
208f0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
20900 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20910 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20920 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20930 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20940 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
20950 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
20960 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20970 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
20980 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
20990 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
209a0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
209b0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
209c0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
209d0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
209e0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
209f0 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
20a00 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
20a10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
20a20 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
20a30 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
20a40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
20a50 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
20a60 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
20a70 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
20a80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20a90 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
20aa0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
20ab0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
20ac0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
20ad0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
20ae0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
20af0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
20b00 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
20b10 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
20b20 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
20b30 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
20b40 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
20b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20b60 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
20b70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
20b80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
20b90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
20ba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20bb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
20bc0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
20bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
20be0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
20bf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
20c00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
20c10 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
20c20 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
20c30 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
20c40 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
20c50 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
20c60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
20c70 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
20c80 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
20c90 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
20ca0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
20cb0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
20cc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
20cd0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
20ce0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
20cf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
20d00 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
20d10 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
20d20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
20d30 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
20d40 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
20d50 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
20d60 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
20d70 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
20d80 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
20d90 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
20da0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
20db0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
20dc0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20dd0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
20de0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
20df0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
20e00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
20e10 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
20e20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
20e30 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
20e40 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
20e50 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
20e60 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  TE])..*/.int sql
20e70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
20e80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
20e90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
20ea0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
20eb0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
20ec0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
20ed0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
20ee0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
20ef0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
20f00 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
20f10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
20f20 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
20f30 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
20f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20f50 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
20f60 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
20f70 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
20f80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
20f90 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
20fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20fb0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
20fc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
20fd0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
20fe0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
20ff0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
21000 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
21010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21020 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
21030 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
21040 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
21050 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
21060 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
21070 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
21080 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
21090 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
210a0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
210b0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
210c0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
210d0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
210e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
210f0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
21100 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
21110 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
21120 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
21130 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
21140 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
21150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
21160 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
21170 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
21180 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
21190 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
211a0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
211b0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
211c0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
211d0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
211e0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
211f0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
21200 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
21210 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
21220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
21230 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
21240 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
21250 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
21260 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
21270 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
21280 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
21290 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
212a0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
212b0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
212c0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
212d0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
212e0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
212f0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
21300 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
21310 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
21320 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
21330 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
21340 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
21350 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21360 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
21370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21380 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
21390 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
213a0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
213b0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
213c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
213d0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
213e0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
213f0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
21400 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
21410 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
21420 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
21430 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
21440 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
21450 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
21460 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
21470 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
21480 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
21490 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
214a0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
214b0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
214c0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
214d0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
214e0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
214f0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
21500 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
21510 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
21520 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
21530 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
21540 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
21550 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
21560 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
21570 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
21580 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
21590 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
215a0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
215b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
215c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
215d0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
215e0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
215f0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
21600 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
21610 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
21620 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
21630 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
21640 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
21650 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
21660 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
21670 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
21680 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
21690 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
216a0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
216b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
216c0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
216d0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
216e0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
216f0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
21700 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
21710 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
21720 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
21730 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
21740 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
21750 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
21760 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
21770 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
21780 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
21790 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
217a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
217b0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
217c0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
217d0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
217e0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
217f0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
21800 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
21810 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
21820 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
21830 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
21840 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
21850 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
21860 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
21870 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
21880 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
21890 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
218a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
218b0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
218c0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
218d0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
218e0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
218f0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
21900 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
21910 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
21920 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
21930 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
21940 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
21950 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
21960 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
21970 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
21980 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
21990 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
219a0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
219b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
219c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
219d0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
219e0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
219f0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
21a00 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
21a10 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
21a20 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
21a30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
21a40 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
21a50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21a60 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
21a70 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
21a80 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
21a90 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
21aa0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
21ab0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
21ac0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
21ad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
21ae0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
21af0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
21b00 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
21b10 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
21b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21b30 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
21b40 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
21b50 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
21b60 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
21b70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
21b80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21b90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
21ba0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
21bb0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21bc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21bd0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
21be0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
21bf0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
21c00 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
21c10 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
21c20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21c30 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
21c40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
21c50 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
21c60 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
21c70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21c80 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
21c90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
21ca0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21cb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21cc0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
21cd0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21ce0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
21cf0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
21d00 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
21d10 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
21d20 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
21d30 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
21d40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21d50 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
21d60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
21d70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
21d80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
21d90 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
21da0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
21db0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
21dc0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
21dd0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
21de0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
21df0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
21e00 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
21e10 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
21e20 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
21e30 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
21e40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
21e50 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
21e60 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
21e70 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
21e80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
21e90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
21ea0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
21eb0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
21ec0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
21ed0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
21ee0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
21ef0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
21f00 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
21f10 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
21f20 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
21f30 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
21f40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
21f50 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
21f60 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
21f70 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
21f80 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
21f90 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
21fa0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
21fb0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
21fc0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
21fd0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
21fe0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
21ff0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
22000 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
22010 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
22020 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
22030 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
22040 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
22050 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
22060 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
22070 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
22080 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
22090 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
220a0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
220b0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
220c0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
220d0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
220e0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
220f0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
22100 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
22110 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
22120 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
22130 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
22140 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
22150 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
22160 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
22170 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
22180 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
22190 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
221a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
221b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
221c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
221d0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
221e0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
221f0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
22200 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
22210 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
22220 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
22230 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
22240 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
22250 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
22260 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22270 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
22280 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
22290 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
222a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
222b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
222c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
222d0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
222e0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
222f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
22300 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
22310 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
22320 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
22330 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
22340 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
22350 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
22360 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
22370 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
22380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
22390 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
223a0 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
223b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
223c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
223d0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
223e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
223f0 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
22400 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
22410 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
22420 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
22430 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
22440 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
22450 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
22460 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
22470 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
22480 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
22490 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
224a0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
224b0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
224c0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
224d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
224e0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
224f0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
22500 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
22510 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
22520 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
22530 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
22540 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
22550 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
22560 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
22570 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
22580 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
22590 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
225a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
225b0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
225c0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
225d0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
225e0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
225f0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
22600 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
22610 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
22620 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
22630 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
22640 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
22650 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
22660 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
22670 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
22680 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
22690 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
226a0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
226b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
226c0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
226d0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
226e0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
226f0 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
22700 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
22710 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
22720 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
22730 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
22740 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
22750 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
22760 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
22770 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
22780 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
22790 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
227a0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
227b0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
227c0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
227d0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
227e0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
227f0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
22800 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22810 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
22820 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
22830 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
22840 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
22850 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
22860 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
22870 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
22880 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
22890 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
228a0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
228b0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
228c0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
228d0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
228e0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
228f0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
22900 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
22910 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
22920 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
22930 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
22940 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
22950 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
22960 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
22970 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
22980 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
22990 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
229a0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
229b0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
229c0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
229d0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
229e0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
229f0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
22a00 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
22a10 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
22a20 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
22a30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
22a40 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
22a50 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
22a60 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
22a70 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
22a80 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
22a90 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
22aa0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
22ab0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
22ac0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
22ad0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
22ae0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
22af0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
22b00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22b10 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
22b20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
22b30 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
22b40 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
22b50 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
22b60 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
22b70 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
22b80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
22b90 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
22ba0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
22bb0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
22bc0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
22bd0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
22be0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
22bf0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
22c00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22c10 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
22c20 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
22c30 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
22c40 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
22c50 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
22c60 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
22c70 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
22c80 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
22c90 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
22ca0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
22cb0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
22cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22cd0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
22ce0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
22cf0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
22d00 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
22d10 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
22d20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
22d30 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
22d40 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
22d50 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71 75  3.1, it was requ
22d60 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71  ired.** after sq
22d70 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
22d80 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f  urned anything o
22d90 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22da0 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b  E_ROW] that.** [
22db0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22dc0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
22dd0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
22de0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
22df0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
22e00 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e  .  Failure to in
22e10 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  voke [sqlite3_re
22e20 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77  set()] in this w
22e30 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75  ay would.** resu
22e40 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
22e50 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
22e60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65  from sqlite3_ste
22e70 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a  p().  But after.
22e80 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  ** version 3.6.2
22e90 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
22ea0 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e  p() began callin
22eb0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
22ec0 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  ()] .** automati
22ed0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
22ee0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
22ef0 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  r than returning
22f00 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
22f10 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  .  .**.** <b>Goo
22f20 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
22f30 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
22f40 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
22f50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
22f60 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
22f70 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
22f80 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
22f90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
22fa0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
22fb0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
22fc0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
22fd0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
22fe0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
22ff0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
23000 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
23010 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
23020 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
23030 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
23040 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
23050 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
23060 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
23070 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
23080 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
23090 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
230a0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
230b0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
230c0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
230d0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
230e0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
230f0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
23100 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
23110 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
23120 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
23130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23140 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
23150 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
23160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23170 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23180 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
23190 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
231a0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
231b0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
231c0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
231d0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
231e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
231f0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
23200 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
23210 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
23220 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
23230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
23240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23250 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
23260 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
23270 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
23280 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
23290 74 28 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20  t(P) the number 
232a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
232b0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
232c0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
232d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
232e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
232f0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
23300 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
23310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23320 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
23330 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
23340 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
23350 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
23360 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
23370 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
23380 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
23390 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
233a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
233b0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
233c0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
233d0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
233e0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
233f0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
23400 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
23410 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
23420 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
23430 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
23440 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
23450 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
23460 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
23470 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
23480 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
23490 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
234a0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
234b0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
234c0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
234d0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
234e0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
234f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
23500 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
23510 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
23520 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
23530 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
23540 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
23550 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
23560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
23570 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
23580 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
23590 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
235a0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
235b0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
235c0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
235d0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
235e0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
235f0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
23600 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
23610 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
23620 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
23630 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
23640 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
23650 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
23660 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
23670 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
23680 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
23690 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
236a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
236b0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
236c0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
236d0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
236e0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
236f0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
23700 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
23710 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
23720 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23730 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
23740 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23750 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
23760 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
23770 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
23780 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
23790 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
237a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
237b0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
237c0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
237d0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
237e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
237f0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
23800 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
23810 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
23820 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
23830 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
23840 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
23850 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
23860 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
23870 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
23880 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
23890 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
238a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
238b0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
238c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
238d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
238e0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
238f0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
23900 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
23910 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
23920 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
23930 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
23940 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
23950 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
23960 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
23970 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
23980 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
23990 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
239a0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
239b0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
239c0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
239d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
239e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
239f0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
23a00 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
23a10 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
23a20 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23a30 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
23a40 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23a50 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23a60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
23a70 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
23a80 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
23a90 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
23aa0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
23ab0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
23ac0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
23ad0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
23ae0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
23af0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23b00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
23b10 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
23b20 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
23b30 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
23b40 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
23b50 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
23b60 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
23b70 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
23b80 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
23b90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23ba0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
23bb0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
23bc0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
23bd0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
23be0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
23bf0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
23c00 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
23c10 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
23c20 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
23c30 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
23c40 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
23c50 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
23c60 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
23c70 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
23c80 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
23c90 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
23ca0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
23cb0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
23cc0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
23cd0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
23ce0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
23cf0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
23d00 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
23d10 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
23d20 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
23d30 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
23d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
23d50 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
23d60 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
23d70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23d80 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
23d90 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
23da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
23db0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
23dc0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
23dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23de0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
23df0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
23e00 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
23e10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23e20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
23e30 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
23e40 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
23e50 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
23e60 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
23e70 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
23e80 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
23e90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23ea0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
23eb0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
23ec0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
23ed0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
23ee0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
23ef0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
23f00 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
23f10 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
23f20 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
23f30 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
23f40 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
23f50 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
23f60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
23f70 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
23f80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23f90 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
23fa0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
23fb0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
23fc0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
23fd0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
23fe0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
23ff0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
24000 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
24010 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
24020 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
24030 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
24040 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
24050 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
24060 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
24070 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
24080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24090 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
240a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
240b0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
240c0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
240d0 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
240e0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
240f0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
24100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24110 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
24120 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
24130 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
24140 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
24150 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
24160 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
24170 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24180 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
24190 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
241a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
241b0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
241c0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
241d0 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
241e0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
241f0 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
24200 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65  .** ^The zero te
24210 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
24220 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
24230 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54   count..**.** ^T
24240 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
24250 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
24260 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
24270 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
24280 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24290 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
242a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
242b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
242c0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
242d0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
242e0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
242f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
24300 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
24310 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
24320 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
24330 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
24340 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
24350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
24360 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
24370 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
24380 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
24390 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
243a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
243b0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
243c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
243d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
243e0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
243f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24400 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
24410 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24420 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
24430 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
24440 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
24450 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
24460 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
24470 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
24480 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
24490 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
244a0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
244b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
244c0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
244d0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
244e0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
244f0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
24500 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
24510 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
24520 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
24530 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
24540 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
24550 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
24560 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
24570 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
24580 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
24590 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
245a0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
245b0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
245c0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
245d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
245e0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
245f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
24600 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
24610 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
24620 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
24630 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24640 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
24650 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
24660 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
24670 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24680 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
24690 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
246a0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
246b0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
246c0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
246d0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
246e0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
246f0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
24700 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
24710 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
24720 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
24730 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
24740 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
24750 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
24760 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
24770 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
24780 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
24790 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
247a0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
247b0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
247c0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
247d0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
247e0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
247f0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
24800 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
24810 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
24820 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
24830 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
24840 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
24850 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
24860 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
24870 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24880 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
24890 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
248a0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
248b0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
248c0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
248d0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
248e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
248f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
24900 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
24910 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
24920 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24930 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
24940 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
24950 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
24960 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
24970 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
24980 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
24990 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
249a0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
249b0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
249c0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
249d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
249e0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
249f0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
24a00 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
24a10 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
24a20 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
24a30 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
24a40 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
24a50 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
24a60 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
24a70 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
24a80 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
24a90 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
24aa0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
24ab0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
24ac0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
24ad0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
24ae0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
24af0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
24b00 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  ammers..**.** ^N
24b10 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
24b20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
24b30 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
24b40 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
24b50 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
24b60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24b70 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
24b80 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
24b90 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
24ba0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
24bb0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
24bc0 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65  .** ^(Type conve
24bd0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
24be0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
24bf0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
24c00 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
24c10 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
24c20 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
24c30 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
24c40 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
24c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24c60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
24c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24c80 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
24c90 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
24ca0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
24cb0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
24cc0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
24cd0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
24ce0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
24cf0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
24d00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
24d10 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
24d20 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
24d30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24d40 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
24d50 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
24d60 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
24d70 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
24d80 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
24d90 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
24da0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
24db0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
24dc0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
24dd0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
24de0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
24df0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
24e00 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
24e10 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
24e20 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
24e30 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ul>)^.**.** ^Con
24e40 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
24e50 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
24e60 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
24e70 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
24e80 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
24e90 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
24ea0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
24eb0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
24ec0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
24ed0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
24ee0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
24ef0 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
24f00 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
24f10 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
24f20 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
24f30 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
24f40 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
24f50 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
24f60 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
24f70 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
24f80 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
24f90 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
24fa0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
24fb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66  .**.** ^(The saf
24fc0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
24fd0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
24fe0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
24ff0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
25000 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
25010 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
25020 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
25030 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
25040 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
25050 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25060 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
25070 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
25080 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
25090 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
250a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
250b0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
250c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
250d0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
250e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
250f0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
25100 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
25110 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
25120 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
25130 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
25140 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
25150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
25160 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
25170 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
25180 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
25190 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
251a0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
251b0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
251c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
251d0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
251e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
251f0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
25200 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
25210 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
25220 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
25230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25240 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
25250 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
25260 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
25270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25280 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
25290 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
252a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
252b0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
252c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
252d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
252e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
252f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
25300 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
25310 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
25320 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
25330 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
25340 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
25350 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
25360 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
25370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
25380 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
25390 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
253a0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
253b0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
253c0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
253d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
253e0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
253f0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
25400 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
25410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
25420 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
25430 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
25440 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
25450 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
25460 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
25470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
25480 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
25490 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
254a0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
254b0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
254c0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
254d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
254e0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
254f0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
25500 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
25510 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
25520 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
25530 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
25540 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
25550 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
25560 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
25570 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
25580 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
25590 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
255a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
255b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
255c0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
255d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
255e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
255f0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
25600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25610 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25620 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
25630 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
25640 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
25650 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25660 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
25670 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
25680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25690 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
256a0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
256b0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
256c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
256d0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
256e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
256f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
25700 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25710 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
25720 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25730 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
25740 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
25760 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
25770 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25780 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
25790 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
257a0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
257b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
257c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
257d0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
257e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
257f0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
25800 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
25810 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
25820 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
25830 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25840 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
25850 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
25860 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  s executed succe
25870 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65  ssfully or not e
25880 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
25890 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  then.** SQLITE_O
258a0 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e  K is returned. ^
258b0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
258c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
258d0 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
258e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
258f0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
25900 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
25910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
25920 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
25930 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
25940 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
25950 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
25960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25970 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20  ment].  ^If the 
25980 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
25990 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
259a0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
259b0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
259c0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
259d0 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
259e0 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
259f0 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
25a00 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
25a10 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63  errupt]..** ^Inc
25a20 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
25a30 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
25a40 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
25a50 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
25a60 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
25a70 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
25a80 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
25a90 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
25aa0 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
25ab0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74  E_ABORT]..*/.int
25ac0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
25ad0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
25ae0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25af0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
25b00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25b10 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
25b20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
25b30 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
25b40 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
25b50 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25b60 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
25b70 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
25b80 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
25b90 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
25ba0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
25bb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
25bc0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
25bd0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
25be0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
25bf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25c00 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
25c10 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
25c20 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
25c30 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
25c40 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25c50 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
25c60 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
25c70 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
25c80 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
25c90 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
25ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25cb0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
25cc0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
25cd0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
25ce0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
25cf0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
25d00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25d10 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
25d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25d30 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
25d40 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
25d50 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
25d60 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
25d70 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
25d80 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
25d90 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
25da0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25db0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
25dc0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
25dd0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
25de0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
25df0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
25e00 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
25e10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
25e20 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
25e30 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
25e40 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
25e50 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
25e60 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
25e70 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
25e80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25e90 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
25ea0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
25eb0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
25ec0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25ed0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
25ee0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25ef0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
25f00 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
25f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25f20 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25f30 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
25f40 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
25f50 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
25f60 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
25f70 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
25f80 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
25f90 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
25fa0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25fb0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
25fc0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
25fd0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25fe0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
25ff0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
26000 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
26010 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
26020 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
26030 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
26040 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
26050 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
26060 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
26070 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
26080 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
26090 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
260a0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
260b0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
260c0 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
260d0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
260e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
260f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26100 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
26110 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
26120 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
26130 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
26140 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26150 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
26160 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
26170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26180 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  6()..**.** ^The 
26190 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
261a0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
261b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
261c0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
261d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
261e0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
261f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
26200 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
26210 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
26220 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
26230 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26240 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
26250 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
26260 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
26270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
26280 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
26290 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
262a0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
262b0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
262c0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
262d0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
262e0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
262f0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
26300 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
26310 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
26320 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
26330 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
26340 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
26350 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
26360 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
26370 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20  aracters.  ^Any 
26380 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
26390 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
263a0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
263b0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
263c0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
263d0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
263e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
263f0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
26400 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
26410 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
26420 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
26430 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
26440 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
26450 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
26460 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
26470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
26480 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
26490 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
264a0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
264b0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
264c0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
264d0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
264e0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
264f0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
26500 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
26510 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
26520 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
26530 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
26540 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26550 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
26560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
26570 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
26580 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
26590 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
265a0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
265b0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
265c0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
265d0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
265e0 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
265f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
26600 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
26610 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
26620 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
26630 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
26640 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
26650 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
26660 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
26670 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
26680 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
26690 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
266a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
266b0 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
266c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
266d0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
266e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
266f0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
26700 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
26710 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
26720 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
26730 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
26740 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
26750 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
26760 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
26770 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
26780 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
26790 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
267a0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
267b0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
267c0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
267d0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
267e0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
267f0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
26800 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
26810 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
26820 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
26830 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
26840 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
26850 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
26860 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
26870 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
26880 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
26890 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
268a0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
268b0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
268c0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
268d0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
268e0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
268f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
26900 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].)^.**.** The 
26910 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
26920 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
26930 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
26940 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
26950 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
26960 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
26970 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
26980 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
26990 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
269a0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
269b0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
269c0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
269d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
269e0 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
269f0 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
26a00 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
26a10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
26a20 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
26a30 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
26a40 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
26a50 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
26a60 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
26a70 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
26a80 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
26a90 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
26aa0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
26ab0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
26ac0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
26ad0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
26ae0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
26af0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
26b00 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
26b10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
26b20 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
26b30 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
26b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
26b50 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
26b60 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
26b70 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
26b80 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
26b90 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
26ba0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
26bb0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
26bc0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
26bd0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
26be0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
26bf0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
26c00 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
26c10 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
26c20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
26c30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
26c40 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
26c50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26c60 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
26c70 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
26c80 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
26c90 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
26ca0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
26cb0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
26cc0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
26cd0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
26ce0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
26cf0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
26d00 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
26d10 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
26d20 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
26d30 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
26d40 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
26d50 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
26d60 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
26d70 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
26d80 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
26d90 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
26da0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
26db0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
26dc0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
26dd0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
26de0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
26df0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
26e00 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
26e10 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
26e20 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
26e30 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
26e40 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
26e50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26e60 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ions..** ^The fi
26e70 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
26e80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26e90 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
26ea0 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
26eb0 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
26ec0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
26ed0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
26ee0 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
26ef0 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
26f00 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c  ^Subsequent appl
26f10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26f20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  functions of the
26f30 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20   same name only 
26f40 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69  override .** pri
26f50 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  or application-d
26f60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
26f70 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61   that are an exa
26f80 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65  ct match for the
26f90 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  .** number of pa
26fa0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65  rameters and pre
26fb0 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e  ferred encoding.
26fc0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
26fd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26fe0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
26ff0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
27000 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
27010 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
27020 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
27030 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
27040 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
27050 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
27060 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
27070 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
27080 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
27090 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
270a0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
270b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
270c0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
270d0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
270e0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
270f0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
27100 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
27110 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
27120 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
27130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27140 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
27150 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
27160 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
27170 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
27180 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
27190 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
271a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
271b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
271c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
271d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
271e0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
271f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
27200 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
27210 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
27220 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
27230 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
27240 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
27250 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
27260 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
27270 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27280 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
27290 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
272a0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
272b0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
272c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
272d0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
272e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
272f0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
27300 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
27310 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
27320 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
27330 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
27340 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
27350 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
27360 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
27370 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27380 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
27390 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
273a0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
273b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
273c0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
273d0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
273e0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
273f0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
27400 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
27410 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27420 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
27430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27440 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
27450 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
27460 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
27470 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
27480 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
27490 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
274a0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
274b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
274c0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
274d0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
274e0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
274f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
27500 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
27510 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
27520 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
27530 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
27540 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
27550 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
27560 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
27570 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
27580 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
27590 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
275a0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
275b0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
275c0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
275d0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
275e0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
275f0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
27600 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
27610 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
27620 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
27630 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
27640 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
27650 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
27660 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
27670 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
27680 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
27690 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
276a0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
276b0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
276c0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
276d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
276e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
276f0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
27700 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
27710 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
27720 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
27730 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
27740 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
27750 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
27760 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
27770 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
27780 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
27790 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
277a0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
277b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
277c0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
277d0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
277e0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
277f0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
27800 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
27810 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
27820 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
27830 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
27840 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
27850 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
27860 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
27870 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
27880 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
27890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
278a0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
278b0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
278c0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
278d0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
278e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
278f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
27900 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27910 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27920 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
27930 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
27940 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
27950 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
27960 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
27970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
27980 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
27990 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
279a0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
279b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
279c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
279d0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
279e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
279f0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
27a00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
27a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
27a20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
27a30 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
27a40 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
27a50 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
27a60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
27a70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27a80 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
27a90 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
27aa0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27ab0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
27ac0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
27ad0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
27ae0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
27af0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
27b00 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
27b10 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
27b20 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
27b30 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
27b40 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
27b50 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
27b60 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
27b70 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
27b80 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
27b90 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
27ba0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
27bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27bc0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
27bd0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
27be0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
27bf0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
27c00 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
27c10 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
27c20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27c30 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
27c40 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
27c50 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
27c60 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
27c70 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
27c80 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
27c90 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
27ca0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
27cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27cc0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
27cd0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
27ce0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
27cf0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
27d00 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
27d10 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
27d20 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
27d30 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
27d40 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
27d50 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
27d60 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
27d70 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
27d80 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
27d90 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
27da0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
27db0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
27dc0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
27dd0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
27de0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
27df0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
27e00 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
27e10 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
27e20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
27e30 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
27e40 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
27e50 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
27e60 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
27e70 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
27e80 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
27e90 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
27ea0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
27eb0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
27ec0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
27ed0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
27ee0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
27ef0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
27f00 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
27f10 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
27f20 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
27f30 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
27f40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
27f50 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
27f60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27f70 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
27f80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
27f90 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
27fa0 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
27fb0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
27fc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27fd0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
27fe0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
27ff0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
28000 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
28010 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
28020 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
28030 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28040 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
28050 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
28060 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
28070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
28080 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
28090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
280a0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
280b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
280c0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
280d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
280e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
280f0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
28100 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28110 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
28120 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
28130 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
28140 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
28150 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28160 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28170 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
28180 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
28190 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
281a0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
281b0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
281c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
281d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
281e0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
281f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28210 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
28220 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
28230 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
28240 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
28250 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
28260 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
28270 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
28280 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
28290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
282a0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
282b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
282c0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
282d0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
282e0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
282f0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
28300 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
28310 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
28320 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61  plementions of a
28330 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
28340 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
28350 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
28360 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
28370 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
28380 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
28390 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
283a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
283b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
283c0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
283d0 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
283e0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
283f0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
28400 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
28410 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
28420 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
28430 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
28440 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
28450 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
28460 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
28470 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
28480 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
28490 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
284a0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
284b0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
284c0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
284d0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
284e0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
284f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28500 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
28510 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
28520 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
28530 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
28540 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
28550 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
28560 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
28570 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
28580 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
28590 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
285a0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
285b0 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
285c0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
285d0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
285e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
285f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
28600 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
28610 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
28620 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
28630 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
28640 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
28650 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
28660 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
28670 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
28680 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
28690 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
286a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
286b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
286c0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
286d0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
286e0 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
286f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
28700 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
28710 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28720 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
28730 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
28740 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
28750 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
28760 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28770 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
28780 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
28790 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
287a0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
287b0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
287c0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
287d0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
287e0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
287f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28800 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
28810 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
28820 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
28830 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
28840 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
28850 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
28860 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
28870 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
28880 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
28890 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
288a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
288b0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
288c0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
288d0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
288e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
288f0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
28900 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
28910 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
28920 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
28930 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
28940 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
28950 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
28960 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
28970 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
28980 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
28990 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
289a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
289b0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
289c0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
289d0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
289e0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
289f0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
28a00 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
28a10 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
28a20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28a30 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
28a40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
28a50 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
28a60 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
28a70 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
28a80 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
28a90 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
28aa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28ab0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
28ac0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
28ad0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
28ae0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
28af0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
28b00 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
28b10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28b20 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
28b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28b40 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
28b50 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
28b60 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
28b70 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
28b80 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
28b90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
28ba0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
28bb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
28bc0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
28bd0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
28be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28bf0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
28c00 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
28c10 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
28c20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28c30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28c40 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
28c50 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
28c60 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
28c70 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28c80 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
28c90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
28ca0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
28cb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
28cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28cd0 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
28ce0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
28cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
28d00 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
28d10 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
28d20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
28d30 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
28d40 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
28d50 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
28d60 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
28d70 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
28d80 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
28d90 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
28da0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
28db0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
28dc0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
28dd0 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
28de0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28df0 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
28e00 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
28e10 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
28e20 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
28e30 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
28e40 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
28e50 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
28e60 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
28e70 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
28e80 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
28e90 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
28ea0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
28eb0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
28ec0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
28ed0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
28ee0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
28ef0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
28f00 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
28f10 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
28f20 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
28f30 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
28f40 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
28f50 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
28f60 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
28f70 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
28f80 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
28f90 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
28fa0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
28fb0 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
28fc0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
28fd0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
28fe0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
28ff0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
29000 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29010 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
29020 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
29030 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
29040 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
29050 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
29060 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
29070 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
29080 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
29090 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
290a0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
290b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
290c0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
290d0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
290e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
290f0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
29100 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
29110 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
29120 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
29130 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
29140 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
29150 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29160 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
29170 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
29180 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
29190 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
291a0 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
291b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
291c0 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
291d0 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
291e0 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
291f0 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
29200 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
29210 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
29220 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
29230 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
29240 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
29250 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
29260 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
29270 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
29280 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
29290 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
292a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
292b0 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
292c0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
292d0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
292e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
292f0 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
29300 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
29310 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
29320 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
29330 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
29340 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
29350 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
29360 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
29370 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
29380 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
29390 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
293a0 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
293b0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
293c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
293d0 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
293e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
293f0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
29400 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
29410 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
29420 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
29430 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
29440 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
29450 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
29460 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
29470 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
29480 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
29490 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
294a0 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
294b0 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
294c0 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
294d0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
294e0 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
294f0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
29500 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
29510 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
29520 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
29530 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
29540 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
29550 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
29560 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
29570 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
29580 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
29590 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
295a0 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
295b0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
295c0 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
295d0 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
295e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
295f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
29600 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
29610 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
29620 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
29630 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
29640 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
29650 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
29660 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
29670 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
29680 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
29690 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
296a0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
296b0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
296c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
296d0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
296e0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
296f0 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
29700 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
29710 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
29720 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
29730 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
29740 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
29750 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
29760 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
29770 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
29780 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
29790 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
297a0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
297b0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
297c0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
297d0 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
297e0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
297f0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
29800 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
29810 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
29820 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
29830 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
29840 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
29850 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
29860 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
29870 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
29880 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
29890 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
298a0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
298b0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
298c0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
298d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
298e0 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
298f0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
29900 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
29910 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
29920 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
29930 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
29940 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
29950 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
29960 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
29970 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
29980 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
29990 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
299a0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
299b0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
299c0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
299d0 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
299e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
299f0 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
29a00 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
29a10 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
29a20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
29a30 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
29a40 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
29a50 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
29a60 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
29a70 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
29a80 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
29a90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29aa0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
29ab0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29ac0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
29ad0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
29ae0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
29af0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
29b00 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
29b10 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
29b20 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
29b30 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
29b40 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
29b50 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
29b60 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
29b70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b80 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
29b90 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
29ba0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
29bb0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
29bc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
29bd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29be0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
29bf0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
29c00 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
29c10 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
29c20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29c30 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
29c40 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
29c50 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
29c60 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
29c70 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
29c80 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
29c90 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
29ca0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
29cb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
29cc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
29cd0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
29ce0 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
29cf0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
29d00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29d10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
29d20 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
29d30 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
29d40 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
29d50 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
29d60 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
29d70 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29d80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
29d90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
29da0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
29db0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
29dc0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
29dd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29de0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
29df0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
29e00 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
29e10 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
29e20 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
29e30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29e40 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
29e50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29e60 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
29e70 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
29e80 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
29e90 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
29ea0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
29eb0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
29ec0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
29ed0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
29ee0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
29ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29f00 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
29f10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
29f20 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
29f30 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
29f40 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
29f50 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
29f60 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
29f70 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
29f80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
29f90 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
29fa0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
29fb0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
29fc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29fd0 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
29fe0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
29ff0 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
2a000 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2a010 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a020 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2a030 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2a040 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
2a050 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
2a060 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
2a070 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2a080 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
2a090 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
2a0a0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
2a0b0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2a0c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2a0d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a0e0 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
2a0f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a100 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
2a110 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2a120 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
2a130 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
2a140 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
2a150 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2a160 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
2a170 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
2a180 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a190 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2a1a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a1b0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
2a1c0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
2a1d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
2a1e0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2a1f0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
2a200 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
2a210 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2a220 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
2a230 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
2a240 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
2a250 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
2a260 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
2a270 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a280 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
2a290 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
2a2a0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
2a2b0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
2a2c0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
2a2d0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
2a2e0 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
2a2f0 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
2a300 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
2a310 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
2a320 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2a330 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2a340 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2a350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a360 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
2a370 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
2a380 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
2a390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a3a0 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
2a3b0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
2a3c0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2a3d0 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
2a3e0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
2a3f0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
2a400 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
2a410 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
2a420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a430 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
2a440 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2a450 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2a460 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2a470 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
2a480 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
2a490 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
2a4a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2a4b0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
2a4c0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2a4d0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2a4e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a4f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2a500 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
2a510 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2a520 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2a530 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2a540 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a550 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
2a560 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2a570 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2a580 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2a590 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2a5a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2a5b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2a5c0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2a5d0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2a5e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2a5f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a600 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
2a610 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2a620 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2a630 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a640 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2a650 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
2a660 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a670 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
2a680 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a690 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
2a6a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a6b0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
2a6c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a6d0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
2a6e0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
2a6f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
2a700 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a710 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2a720 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
2a730 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
2a740 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
2a750 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
2a760 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
2a770 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
2a780 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2a790 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
2a7a0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
2a7b0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
2a7c0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
2a7d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
2a7e0 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
2a7f0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2a800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a810 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
2a820 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
2a830 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2a840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a850 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2a860 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2a870 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2a880 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2a890 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2a8a0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
2a8b0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2a8c0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
2a8d0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2a8e0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2a8f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2a900 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2a910 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2a920 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
2a930 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2a940 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
2a950 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2a960 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a970 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
2a980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a990 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
2a9a0 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
2a9b0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2a9c0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2a9d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2a9e0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2a9f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2aa00 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2aa10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2aa20 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2aa30 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2aa40 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2aa50 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2aa60 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
2aa70 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2aa80 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2aa90 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2aaa0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2aab0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2aac0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2aad0 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
2aae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2aaf0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2ab00 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2ab10 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
2ab20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
2ab30 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
2ab40 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
2ab50 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
2ab60 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2ab70 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
2ab80 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
2ab90 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
2aba0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2abb0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
2abc0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2abd0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2abe0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2abf0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2ac00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2ac10 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2ac20 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2ac30 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2ac40 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2ac50 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2ac60 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2ac70 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2ac80 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2ac90 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
2aca0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
2acb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2acc0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
2acd0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2ace0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2acf0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2ad00 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2ad10 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2ad20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ad30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2ad40 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2ad50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2ad60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ad70 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2ad80 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2ad90 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
2ada0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2adb0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
2adc0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2add0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ade0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
2adf0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2ae00 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
2ae10 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
2ae20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
2ae30 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
2ae40 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2ae50 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
2ae60 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2ae70 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
2ae80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ae90 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
2aea0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
2aeb0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2aec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2aed0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
2aee0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
2aef0 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
2af00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2af10 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
2af20 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
2af30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
2af40 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2af50 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
2af60 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
2af70 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
2af80 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
2af90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2afa0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2afb0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
2afc0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2afd0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
2afe0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2aff0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2b000 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b010 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2b020 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2b030 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2b040 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2b050 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b060 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2b070 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2b080 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2b090 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2b0a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2b0b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2b0c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2b0d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2b0e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b0f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2b100 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2b110 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2b120 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2b130 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2b140 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b150 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2b160 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2b170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b180 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2b190 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2b1a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2b1b0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2b1c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2b1d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2b1e0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2b1f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2b200 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2b210 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b220 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2b230 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2b240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2b250 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2b260 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2b270 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2b280 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2b290 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b2a0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2b2b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2b2c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2b2d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2b2e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b2f0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2b300 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2b310 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2b320 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2b330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2b340 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2b350 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2b360 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2b370 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2b380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2b390 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2b3a0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2b3b0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2b3c0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2b3d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2b3e0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2b3f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b400 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2b410 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
2b420 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2b430 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
2b440 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
2b450 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
2b460 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2b470 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
2b480 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2b490 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
2b4a0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2b4b0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
2b4c0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
2b4d0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
2b4e0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
2b4f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b500 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
2b510 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b520 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
2b530 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
2b540 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
2b550 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b560 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63  n16(). ^In all c
2b570 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
2b580 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
2b590 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2b5a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2b5b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2b5c0 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
2b5d0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
2b5e0 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
2b5f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
2b600 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6LE], or [SQLITE
2b610 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
2b620 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
2b630 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
2b640 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
2b650 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
2b660 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2b670 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
2b680 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
2b690 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
2b6a0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
2b6b0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2b6c0 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64  y. ^The.** third
2b6d0 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
2b6e0 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
2b6f0 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61  UTF16] to indica
2b700 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74  te that the rout
2b710 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70  ine.** expects p
2b720 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54  ointers to be UT
2b730 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20  F-16 strings in 
2b740 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
2b750 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a  order, or the.**
2b760 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
2b770 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2b780 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a  LIGNED] if the.*
2b790 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
2b7a0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
2b7b0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
2b7c0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
2b7d0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
2b7e0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2b7f0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  der..**.** A poi
2b800 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
2b810 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
2b820 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
2b830 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
2b840 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
2b850 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
2b860 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2b870 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
2b880 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2b890 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
2b8a0 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
2b8b0 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e  t anymore)..** ^
2b8c0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
2b8d0 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
2b8e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
2b8f0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
2b900 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
2b910 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
2b920 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
2b930 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
2b940 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2b950 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2b960 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2b970 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2b980 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2b990 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  )..**.** ^The re
2b9a0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
2b9b0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
2b9c0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
2b9d0 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
2b9e0 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
2b9f0 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
2ba00 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
2ba10 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
2ba20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
2ba30 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
2ba40 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
2ba50 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
2ba60 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
2ba70 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
2ba80 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70 70  stered.  The app
2ba90 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2baa0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
2bab0 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
2bac0 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
2bad0 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
2bae0 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
2baf0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
2bb00 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
2bb10 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
2bb20 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
2bb30 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
2bb40 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
2bb50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
2bb60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2bb70 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
2bb80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2bb90 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
2bba0 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
2bbb0 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
2bbc0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
2bbd0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
2bbe0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
2bbf0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2bc00 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
2bc10 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
2bc20 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
2bc30 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
2bc40 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
2bc50 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
2bc60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
2bc70 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
2bc80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2bc90 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73  ..** ^Collations
2bca0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
2bcb0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
2bcc0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
2bcd0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
2bce0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
2bcf0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
2bd00 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
2bd10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2bd20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
2bd30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2bd40 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  e()]..**.** See 
2bd50 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
2bd60 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2bd70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2bd80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2bd90 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
2bda0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2bdb0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2bdc0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2bdd0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2bde0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2bdf0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2be00 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2be10 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2be20 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2be30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2be40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2be50 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2be60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2be70 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2be80 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2be90 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2bea0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2beb0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2bec0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
2bed0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2bee0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2bef0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2bf00 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
2bf10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2bf20 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
2bf30 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2bf40 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2bf50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2bf60 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2bf70 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2bf80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2bf90 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2bfa0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
2bfb0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
2bfc0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
2bfd0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2bfe0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
2bff0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
2c000 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
2c010 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
2c020 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
2c030 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
2c040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c050 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
2c060 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2c070 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2c080 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2c090 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2c0a0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2c0b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2c0c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2c0d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2c0e0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2c0f0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2c100 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2c110 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2c120 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2c130 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2c140 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2c150 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2c160 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2c170 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2c180 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2c190 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2c1a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2c1b0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2c1c0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2c1d0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
2c1e0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
2c1f0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
2c200 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
2c210 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2c220 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2c230 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2c240 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2c250 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2c260 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2c270 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2c280 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2c290 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2c2a0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2c2b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2c2c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2c2d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
2c2e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2c2f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2c300 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2c310 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
2c320 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2c330 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2c340 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
2c350 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2c360 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2c370 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2c380 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
2c390 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2c3a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2c3b0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2c3c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
2c3d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2c3e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2c3f0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2c400 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2c410 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2c420 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2c430 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2c440 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c450 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2c460 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c470 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2c480 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c490 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2c4a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2c4b0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2c4c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2c4d0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2c4e0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2c4f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2c500 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2c510 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2c520 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2c530 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2c540 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2c550 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
2c560 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
2c570 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
2c580 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2c590 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2c5a0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2c5b0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2c5c0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2c5d0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2c5e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2c5f0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2c600 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2c610 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2c620 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2c630 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2c640 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2c650 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c670 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2c680 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2c690 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2c6a0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2c6b0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2c6c0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2c6d0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2c6e0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2c6f0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2c700 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2c710 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2c720 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2c730 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2c740 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2c750 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2c760 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2c770 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2c780 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2c790 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2c7a0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2c7b0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2c7c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2c7d0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2c7e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2c800 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2c810 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2c820 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2c830 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2c840 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2c850 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2c860 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2c870 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
2c880 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2c890 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2c8a0 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
2c8b0 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2c8c0 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2c8d0 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
2c8e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c8f0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
2c900 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
2c910 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
2c920 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
2c930 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
2c940 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2c950 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
2c960 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
2c970 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2c980 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2c990 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
2c9a0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2c9b0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2c9c0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
2c9d0 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
2c9e0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2c9f0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2ca00 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2ca10 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2ca20 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
2ca30 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2ca40 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
2ca50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c   ^The sqlite3_sl
2ca60 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
2ca70 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
2ca80 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
2ca90 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
2caa0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
2cab0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2cac0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
2cad0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
2cae0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  r..**.** ^If the
2caf0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2cb00 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
2cb10 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
2cb20 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
2cb30 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
2cb40 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
2cb50 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
2cb60 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
2cb70 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
2cb80 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  . ^The number of
2cb90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
2cba0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
2cbb0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
2cbc0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
2cbd0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
2cbe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
2cbf0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
2cc00 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
2cc10 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
2cc20 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
2cc30 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
2cc40 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
2cc50 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2cc60 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
2cc70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2cc80 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2cc90 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2cca0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
2ccb0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
2ccc0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
2ccd0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
2cce0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
2ccf0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
2cd00 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
2cd10 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2cd20 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2cd30 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2cd40 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
2cd50 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
2cd60 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2cd70 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
2cd80 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2cd90 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
2cda0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2cdb0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2cdc0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2cdd0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2cde0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2cdf0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2ce00 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2ce10 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2ce20 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2ce30 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2ce40 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2ce50 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2ce60 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2ce70 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2ce80 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2ce90 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2cea0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2ceb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2cec0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2ced0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2cee0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2cef0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2cf00 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2cf10 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2cf20 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2cf30 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2cf40 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2cf50 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2cf60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2cf70 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2cf80 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2cf90 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2cfa0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2cfb0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2cfc0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2cfd0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2cfe0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2cff0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2d000 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2d010 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2d020 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2d030 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2d040 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2d050 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2d060 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2d070 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2d080 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2d090 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2d0a0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2d0b0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2d0c0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2d0d0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2d0e0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2d0f0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2d100 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2d110 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2d120 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2d130 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2d140 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2d150 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2d160 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2d170 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2d180 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2d190 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2d1a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2d1b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2d1c0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2d1d0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2d1e0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2d1f0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2d200 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2d210 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2d220 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2d230 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2d240 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2d250 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2d260 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2d270 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2d280 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2d290 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2d2a0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2d2b0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2d2c0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2d2d0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2d2e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2d2f0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2d300 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2d310 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2d320 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2d330 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2d340 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2d350 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2d360 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2d370 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2d380 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2d390 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2d3a0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2d3b0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2d3c0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2d3d0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2d3e0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2d3f0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2d400 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2d410 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2d420 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2d430 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2d440 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2d450 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2d460 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2d470 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2d480 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2d490 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2d4a0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2d4b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2d4c0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2d4d0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2d4e0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2d4f0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2d500 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2d510 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2d520 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2d530 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2d540 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2d550 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2d560 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2d570 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2d580 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2d590 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2d5a0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2d5b0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2d5c0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2d5d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
2d5e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2d5f0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
2d600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d610 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
2d620 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2d630 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2d640 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
2d650 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2d660 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
2d670 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
2d680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2d690 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
2d6a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d6b0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2d6c0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
2d6d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2d6e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d6f0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
2d700 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2d710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2d720 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
2d730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2d740 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2d750 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d760 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2d770 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2d780 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2d790 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2d7a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2d7b0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
2d7c0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2d7d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2d7e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d7f0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
2d800 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d810 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
2d820 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d830 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d840 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
2d850 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
2d860 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
2d870 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2d880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d890 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
2d8a0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
2d8b0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
2d8c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2d8d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
2d8e0 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
2d8f0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
2d900 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
2d910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d920 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
2d930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d940 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2d950 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2d960 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2d970 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2d980 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2d990 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2d9a0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2d9b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2d9c0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2d9d0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2d9e0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2d9f0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2da00 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2da10 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2da20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2da30 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
2da40 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2da50 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
2da60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2da70 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2da80 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2da90 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2daa0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2dab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dac0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2dad0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2dae0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2daf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2db00 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2db10 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2db20 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2db30 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
2db40 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2db50 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2db60 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2db70 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2db80 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2db90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2dba0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2dbb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2dbc0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
2dbd0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2dbe0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2dbf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2dc00 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2dc10 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2dc20 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
2dc30 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
2dc40 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2dc50 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2dc60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2dc70 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
2dc80 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2dc90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2dca0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2dcb0 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
2dcc0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
2dcd0 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
2dce0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
2dcf0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
2dd00 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
2dd10 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2dd20 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
2dd30 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2dd40 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2dd50 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2dd60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd70 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
2dd80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
2dd90 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
2dda0 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
2ddb0 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
2ddc0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2ddd0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
2dde0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2ddf0 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
2de00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2de10 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2de20 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2de30 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
2de40 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
2de50 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2de60 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
2de70 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
2de80 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
2de90 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
2dea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2deb0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
2dec0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
2ded0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2dee0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2def0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2df00 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2df10 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2df20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2df30 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2df40 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2df50 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
2df60 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
2df70 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
2df80 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
2df90 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2dfa0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2dfb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2dfc0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2dfd0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2dfe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2dff0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2e000 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2e010 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2e020 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
2e030 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
2e040 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
2e050 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2e060 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
2e070 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
2e080 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
2e090 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
2e0a0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
2e0b0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
2e0c0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
2e0d0 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
2e0e0 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
2e0f0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
2e100 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
2e110 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2e120 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
2e130 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
2e140 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
2e150 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
2e160 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
2e170 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
2e180 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
2e190 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
2e1a0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
2e1b0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
2e1c0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
2e1d0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2e1e0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2e1f0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2e200 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2e210 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2e220 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2e230 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2e240 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2e250 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2e260 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2e270 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2e280 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
2e290 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2e2a0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2e2b0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2e2c0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2e2d0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2e2e0 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2e2f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e300 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2e310 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2e320 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2e330 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
2e340 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
2e350 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2e360 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2e370 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2e380 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2e390 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2e3a0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2e3b0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2e3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e3d0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2e3e0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2e3f0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2e400 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2e410 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2e420 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2e430 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
2e440 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2e450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e460 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2e470 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2e480 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
2e490 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
2e4a0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2e4b0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2e4c0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
2e4d0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2e4e0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2e4f0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2e500 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2e510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e520 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2e530 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2e540 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2e550 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
2e560 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
2e570 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
2e580 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2e590 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2e5a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2e5b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2e5c0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2e5d0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2e5e0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2e5f0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2e600 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
2e610 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2e620 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2e630 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2e640 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2e650 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2e660 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2e670 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2e680 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2e690 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2e6a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2e6b0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2e6c0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
2e6d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2e6e0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
2e6f0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
2e700 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
2e710 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
2e720 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
2e730 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
2e740 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2e750 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
2e760 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2e770 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
2e780 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2e790 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2e7a0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2e7b0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2e7c0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
2e7d0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2e7e0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2e7f0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2e800 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2e810 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2e820 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2e830 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
2e840 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
2e850 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2e860 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
2e870 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
2e880 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
2e890 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
2e8a0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
2e8b0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
2e8c0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
2e8d0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
2e8e0 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
2e8f0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2e900 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2e910 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2e920 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2e930 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2e940 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2e950 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2e960 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2e970 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2e980 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2e990 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2e9a0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2e9b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e9c0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2e9d0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2e9e0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2e9f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ea00 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2ea10 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2ea20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2ea30 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2ea40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ea50 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2ea60 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2ea70 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2ea80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2ea90 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2eaa0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2eab0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2eac0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2ead0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2eae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2eaf0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2eb00 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2eb10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2eb20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2eb30 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2eb40 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2eb50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2eb60 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
2eb70 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
2eb80 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
2eb90 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
2eba0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
2ebb0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
2ebc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ebd0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
2ebe0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
2ebf0 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
2ec00 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2ec10 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2ec20 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2ec30 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2ec40 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2ec50 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
2ec60 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2ec70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2ec80 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2ec90 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2eca0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2ecb0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2ecc0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2ecd0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2ece0 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2ecf0 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
2ed00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
2ed10 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
2ed20 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2ed30 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2ed40 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2ed50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2ed60 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2ed70 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2ed80 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2ed90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2eda0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2edb0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2edc0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2edd0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2ede0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2edf0 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2ee00 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2ee10 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
2ee20 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
2ee30 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2ee40 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2ee50 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2ee60 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2ee70 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2ee80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2ee90 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2eea0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2eeb0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2eec0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2eed0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2eee0 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2eef0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
2ef00 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2ef10 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2ef20 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2ef30 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2ef40 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ef50 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2ef60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2ef70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2ef80 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2ef90 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2efa0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2efb0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2efc0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2efd0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2efe0 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2eff0 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
2f000 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2f010 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2f020 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
2f030 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
2f040 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
2f050 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
2f060 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2f070 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
2f080 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
2f090 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2f0a0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2f0b0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2f0c0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2f0d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2f0e0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2f0f0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2f100 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2f110 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2f120 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2f130 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2f140 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2f150 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2f160 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
2f170 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
2f180 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
2f190 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f1a0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2f1b0 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
2f1c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f1d0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2f1e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2f1f0 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
2f200 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
2f210 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
2f220 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
2f230 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
2f240 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
2f250 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
2f260 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
2f270 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2f280 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2f290 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2f2a0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2f2b0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2f2c0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2f2d0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
2f2e0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
2f2f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2f300 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
2f310 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
2f320 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
2f330 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
2f340 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
2f350 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f360 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2f370 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2f380 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
2f390 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
2f3a0 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ze.**.** ^The sq
2f3b0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2f3c0 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2f3d0 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2f3e0 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2f3f0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2f400 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2f410 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2f420 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20   SQLite..** ^If 
2f430 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
2f440 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
2f450 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
2f460 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
2f470 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
2f480 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2f490 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
2f4a0 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
2f4b0 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
2f4c0 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
2f4d0 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
2f4e0 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
2f4f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69  d..**.** ^The li
2f500 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
2f510 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20  oft" because if 
2f520 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2f530 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
2f540 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
2f550 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
2f560 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
2f570 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
2f580 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
2f590 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
2f5a0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
2f5b0 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
2f5c0 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
2f5d0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72  * ^A negative or
2f5e0 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2f5f0 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2f600 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2f610 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2f620 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2f630 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2f640 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2f650 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2f660 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  hausted..** ^The
2f670 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2f680 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2f690 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2f6a0 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d  **.** ^(SQLite m
2f6b0 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2f6c0 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2f6d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2f6e0 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2f6f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2f700 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2f710 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2f720 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2f730 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2f740 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54  tification.)^  T
2f750 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
2f760 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  imit is.** calle
2f770 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
2f780 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
2f790 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
2f7a0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
2f7b0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
2f7c0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
2f7d0 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
2f7e0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2f7f0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
2f800 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
2f810 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2f820 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2f830 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
2f840 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
2f850 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
2f860 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2f870 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
2f880 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
2f890 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
2f8a0 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
2f8b0 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
2f8c0 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2f8d0 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
2f8e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2f8f0 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
2f900 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
2f910 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
2f920 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
2f930 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
2f940 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
2f950 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
2f960 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2f970 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2f980 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2f990 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2f9a0 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2f9b0 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2f9c0 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
2f9d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2f9e0 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2f9f0 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2fa00 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2fa10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2fa20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2fa30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2fa40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2fa50 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2fa60 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2fa70 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2fa80 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2fa90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2faa0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2fab0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2fac0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2fad0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
2fae0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2faf0 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
2fb00 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2fb10 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
2fb20 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
2fb30 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2fb40 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2fb50 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2fb60 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2fb70 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
2fb80 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2fb90 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2fba0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2fbb0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2fbc0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2fbd0 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2fbe0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2fbf0 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2fc00 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2fc10 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2fc20 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
2fc30 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2fc40 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2fc50 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2fc60 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2fc70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2fc80 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2fc90 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2fca0 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2fcb0 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2fcc0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
2fcd0 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
2fce0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
2fcf0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
2fd00 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
2fd10 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
2fd20 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
2fd30 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2fd40 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
2fd50 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2fd60 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
2fd70 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2fd80 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
2fd90 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
2fda0 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
2fdb0 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
2fdc0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2fdd0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2fde0 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
2fdf0 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
2fe00 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
2fe10 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
2fe20 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
2fe30 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
2fe40 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
2fe50 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
2fe60 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
2fe70 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
2fe80 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2fe90 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
2fea0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2feb0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2fec0 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
2fed0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2fee0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
2fef0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2ff00 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2ff10 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
2ff20 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
2ff30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
2ff40 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2ff50 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2ff60 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
2ff70 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
2ff80 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2ff90 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
2ffa0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2ffb0 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2ffc0 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2ffd0 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2ffe0 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2fff0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
30000 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
30010 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
30020 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
30030 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
30040 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
30050 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
30060 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
30070 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
30080 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
30090 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
300a0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
300b0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
300c0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
300d0 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
300e0 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
300f0 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
30100 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
30110 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
30120 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
30130 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
30140 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
30150 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
30160 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
30170 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
30180 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
30190 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
301a0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
301b0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
301c0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
301d0 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
301e0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
301f0 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
30200 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
30210 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
30220 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
30230 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
30240 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
30250 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
30260 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
30270 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
30280 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
30290 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
302a0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
302b0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
302c0 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
302d0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
302e0 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
302f0 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
30300 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
30310 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
30320 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
30330 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
30340 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
30350 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
30360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
30380 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
30390 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
303a0 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
303b0 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
303c0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
303d0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
303e0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
303f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
30400 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
30410 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
30420 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
30430 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
30440 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
30450 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
30460 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
30470 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
30480 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
30490 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
304a0 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
304b0 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
304c0 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
304d0 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
304e0 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
304f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
30500 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
30510 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
30520 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
30530 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
30540 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
30550 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
30560 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
30570 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
30580 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
30590 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
305a0 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
305b0 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
305c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
305d0 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
305e0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
305f0 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
30600 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
30610 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
30620 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
30630 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
30640 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
30650 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
30660 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
30670 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
30680 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
30690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
306a0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
306b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
306c0 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
306d0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
306e0 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
306f0 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
30700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30710 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
30720 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
30730 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
30740 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
30750 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
30760 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
30770 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
30780 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
30790 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
307a0 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
307b0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
307c0 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
307d0 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
307e0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
307f0 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
30800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30810 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
30820 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30830 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
30840 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
30850 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
30860 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
30870 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
30880 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
30890 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
308a0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
308b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
308c0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
308d0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
308e0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
308f0 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
30900 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
30910 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
30920 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
30930 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
30940 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
30950 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
30960 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
30970 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
30980 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
30990 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
309a0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
309b0 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
309c0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
309d0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
309e0 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
309f0 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
30a00 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
30a10 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
30a20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
30a30 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
30a40 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
30a50 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
30a60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30a70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
30a80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
30a90 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
30aa0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
30ab0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
30ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
30ad0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
30ae0 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
30af0 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
30b00 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
30b10 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
30b20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
30b30 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
30b40 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
30b50 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
30b60 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
30b70 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
30b80 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
30b90 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
30ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30bb0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
30bc0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
30bd0 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
30be0 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
30bf0 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
30c00 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
30c10 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
30c20 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
30c30 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
30c40 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
30c50 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
30c60 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
30c70 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
30c80 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
30c90 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
30ca0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
30cb0 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
30cc0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
30cd0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
30ce0 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
30cf0 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
30d00 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
30d10 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
30d20 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
30d30 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
30d40 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
30d50 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30d60 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
30d70 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
30d80 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
30d90 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
30da0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
30db0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
30dc0 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
30dd0 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
30de0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
30df0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
30e00 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
30e10 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
30e20 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
30e30 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
30e40 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
30e50 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
30e60 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
30e70 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
30e80 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
30e90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
30ea0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
30eb0 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
30ec0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
30ed0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b  .** to all new [
30ee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30ef0 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ions]..**.** ^(T
30f00 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
30f10 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
30f20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e  the extension en
30f30 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20  try point.** in 
30f40 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
30f50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
30f60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
30f70 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a  ].  That memory.
30f80 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65  ** is deallocate
30f90 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65  d by [sqlite3_re
30fa0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
30fb0 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  on()].)^.**.** ^
30fc0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
30fd0 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
30fe0 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
30ff0 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f   that is.** auto
31000 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
31010 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
31020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31030 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65  ction].** is ope
31040 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
31050 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
31060 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
31070 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
31080 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44  pen_v2()]..** ^D
31090 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
310a0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
310b0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
310c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74   routine.** mult
310d0 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20  iple times with 
310e0 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
310f0 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
31100 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78  ** ^Automatic ex
31110 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
31120 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
31130 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
31140 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
31150 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
31160 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
31170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
31180 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
31190 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
311a0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
311b0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
311c0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
311d0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
311e0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
311f0 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20  . It undoes the 
31200 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
31210 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
31220 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
31230 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a  ] calls.)^.**.**
31240 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
31250 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
31260 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
31270 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
31280 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31290 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
312a0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
312b0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
312c0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
312d0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
312e0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
312f0 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
31300 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
31310 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
31320 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
31330 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
31340 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
31350 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
31360 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
31370 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
31380 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
31390 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
313a0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
313b0 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
313c0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
313d0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
313e0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
313f0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
31400 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
31410 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
31420 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
31430 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
31440 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
31450 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
31460 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
31470 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
31480 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
31490 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
314a0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
314b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
314c0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
314d0 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
314e0 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
314f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
31500 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
31510 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
31520 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
31530 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  able Object.** K
31540 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
31550 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
31560 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
31570 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
31580 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
31590 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
315a0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
315b0 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
315c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
315d0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
315e0 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
315f0 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
31600 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
31610 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
31620 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
31630 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
31640 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
31650 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
31660 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
31670 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
31680 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
31690 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
316a0 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
316b0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
316c0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
316d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
316e0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
316f0 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
31700 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
31710 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
31720 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
31730 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
31740 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
31750 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31760 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
31770 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
31780 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
31790 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
317a0 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
317b0 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
317c0 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
317d0 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
317e0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
317f0 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
31800 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
31810 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
31820 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
31830 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
31840 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
31850 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
31860 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
31870 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
31880 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
31890 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
318a0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
318b0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
318c0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
318d0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
318e0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
318f0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
31900 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
31910 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
31920 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
31930 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
31940 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
31950 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
31960 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
31970 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31980 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
31990 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
319a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
319b0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
319c0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
319d0 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
319e0 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
319f0 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
31a00 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
31a10 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
31a20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
31a30 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
31a40 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
31a50 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
31a60 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
31a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
31a80 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
31a90 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
31aa0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
31ab0 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
31ac0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
31ad0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
31ae0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
31af0 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
31b00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
31b10 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
31b20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
31b30 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
31b40 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
31b50 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
31b60 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
31b70 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
31b80 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
31b90 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
31ba0 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
31bb0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
31bc0 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
31bd0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31be0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
31bf0 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
31c00 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31c10 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
31c20 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31c30 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
31c40 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
31c50 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
31c60 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
31c70 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
31c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31c90 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
31ca0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31cb0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31cc0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
31cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31ce0 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
31cf0 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
31d00 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31d10 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
31d20 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
31d30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
31d40 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
31d50 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
31d60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
31d70 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
31d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31d90 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
31da0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
31db0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
31dc0 20 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a   used as part.**
31dd0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
31de0 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63   table] interfac
31df0 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  e to.** pass inf
31e00 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
31e10 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
31e20 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
31e30 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
31e40 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
31e50 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
31e60 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
31e70 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
31e80 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
31e90 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
31ea0 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
31eb0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
31ec0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
31ed0 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
31ee0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
31ef0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
31f00 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
31f10 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
31f20 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
31f30 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
31f40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
31f50 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c  >column OP expr<
31f60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
31f70 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d  ** where OP is =
31f80 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
31f90 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e  gt;, or &gt;=.)^
31fa0 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c    ^(The particul
31fb0 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a  ar operator is.*
31fc0 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e  * stored in aCon
31fd0 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69  straint[].op usi
31fe0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ng one of the.**
31ff0 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43   [SQLITE_INDEX_C
32000 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53  ONSTRAINT_EQ | S
32010 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
32020 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e  TRAINT_ values].
32030 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65  )^.** ^(The inde
32040 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
32050 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
32060 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
32070 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e  olumn.)^  ^(aCon
32080 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65  straint[].usable
32090 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a   is TRUE if the.
320a0 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72  ** expr on the r
320b0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63  ight-hand side c
320c0 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  an be evaluated 
320d0 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f  (and thus the co
320e0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75  nstraint.** is u
320f0 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65  sable) and false
32100 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e   if it cannot.)^
32110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69  .**.** ^The opti
32120 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
32130 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
32140 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
32150 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
32160 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
32170 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
32180 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
32190 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
321a0 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
321b0 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
321c0 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
321d0 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
321e0 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
321f0 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61  ** ^The aConstra
32200 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
32210 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
32220 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74  lause terms that
32230 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74   are.** relevant
32240 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
32250 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
32260 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
32270 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69  **.** ^Informati
32280 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44  on about the ORD
32290 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
322a0 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72  stored in aOrder
322b0 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74  By[]..** ^Each t
322c0 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20  erm of aOrderBy 
322d0 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e  records a column
322e0 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
322f0 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54   clause..**.** T
32300 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20  he [xBestIndex] 
32310 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c  method must fill
32320 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
32330 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  e[] with informa
32340 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68  tion.** about wh
32350 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  at parameters to
32360 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72   pass to xFilter
32370 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78  .  ^If argvIndex
32380 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
32390 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
323a0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
323b0 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
323c0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
323d0 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
323e0 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
323f0 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e  ntry in argv.  ^
32400 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  (If aConstraintU
32410 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
32420 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
32430 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
32440 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
32450 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
32460 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
32470 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
32480 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
32490 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  QLite.)^.**.** ^
324a0 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69  The idxNum and i
324b0 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65  dxPtr values are
324c0 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61   recorded and pa
324d0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ssed into the.**
324e0 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f   [xFilter] metho
324f0 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f  d..** ^[sqlite3_
32500 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20  free()] is used 
32510 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
32520 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
32530 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
32540 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
32550 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e   ^The orderByCon
32560 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
32570 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46   output from [xF
32580 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77  ilter]/[xNext] w
32590 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
325a0 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
325b0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
325c0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
325d0 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
325e0 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
325f0 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
32600 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74  ..**.** ^The est
32610 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
32620 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
32630 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
32640 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
32650 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
32660 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
32670 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
32680 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
32690 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
326a0 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
326b0 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
326c0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
326d0 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
326e0 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
326f0 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
32700 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
32710 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
32720 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
32730 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
32740 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
32750 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
32760 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
32770 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
32780 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
32790 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
327a0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
327b0 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
327c0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
327d0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
327e0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
327f0 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
32800 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
32810 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
32820 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
32830 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
32840 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
32850 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
32860 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
32870 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
32880 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
32890 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
328a0 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
328b0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
328c0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
328d0 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
328e0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
328f0 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
32900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32910 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
32920 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
32930 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
32940 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
32950 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
32960 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
32970 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
32980 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
32990 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
329a0 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
329b0 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
329c0 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
329d0 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
329e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
329f0 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
32a00 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f  clause */.  /* O
32a10 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
32a20 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
32a30 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
32a40 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
32a50 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
32a60 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
32a70 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
32a80 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
32a90 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
32aa0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
32ab0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
32ac0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
32ad0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
32ae0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
32af0 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
32b00 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
32b10 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
32b20 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
32b30 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
32b40 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
32b50 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
32b60 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
32b70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
32b80 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
32b90 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
32ba0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
32bb0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
32bc0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
32bd0 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
32be0 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
32bf0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
32c00 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
32c10 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
32c20 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
32c30 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
32c40 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
32c50 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
32c60 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
32c70 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
32c80 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f  ble Constraint O
32c90 70 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a  perator Codes.**
32ca0 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
32cb0 20 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c   defined the all
32cc0 6f 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20  owed values for 
32cd0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
32ce0 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e  index_info].aCon
32cf0 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65  straint[].op fie
32d00 6c 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20  ld.  Each value 
32d10 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e  represents.** an
32d20 20 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69   operator that i
32d30 73 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73  s part of a cons
32d40 74 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74  traint term in t
32d50 68 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20  he wHERE clause 
32d60 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68  of.** a query th
32d70 61 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75  at uses a [virtu
32d80 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64  al table]..*/.#d
32d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32da0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
32db0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
32dc0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32dd0 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64  RAINT_GT    4.#d
32de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32df0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45  EX_CONSTRAINT_LE
32e00 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
32e10 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32e20 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23  RAINT_LT    16.#
32e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
32e40 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
32e50 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
32e60 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
32e70 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34  STRAINT_MATCH 64
32e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32e90 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72  : Register A Vir
32ea0 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65  tual Table Imple
32eb0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  mentation.**.** 
32ec0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32ed0 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69  are used to regi
32ee0 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74  ster a new [virt
32ef0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
32f00 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75  ] name..** ^Modu
32f10 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
32f20 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
32f30 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61  re.** creating a
32f40 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
32f50 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d  ble] using the m
32f60 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65  odule and before
32f70 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65   using a.** pree
32f80 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c  xisting [virtual
32f90 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20   table] for the 
32fa0 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  module..**.** ^T
32fb0 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69  he module name i
32fc0 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20  s registered on 
32fd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32fe0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
32ff0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  ied.** by the fi
33000 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
33010 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
33020 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e   module is given
33030 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f   by the .** seco
33040 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
33050 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
33060 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
33070 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65   to.** the imple
33080 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
33090 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
330a0 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20  module].   ^The 
330b0 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
330c0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
330d0 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ary client data 
330e0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
330f0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
33100 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65  * into the [xCre
33110 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
33120 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ct] methods of t
33130 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
33140 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20   module.** when 
33150 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61  a new virtual ta
33160 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20  ble is be being 
33170 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69  created or reini
33180 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  tialized..**.** 
33190 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
331a0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
331b0 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20  interface has a 
331c0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
331d0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
331e0 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72  inter to a destr
331f0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43  uctor for the pC
33200 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c  lientData.  ^SQL
33210 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f  ite will.** invo
33220 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
33230 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69  r function (if i
33240 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77  t is not NULL) w
33250 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f  hen SQLite.** no
33260 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68   longer needs th
33270 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f  e pClientData po
33280 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c  inter.  ^The sql
33290 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
332a0 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  le().** interfac
332b0 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
332c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
332d0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69  e_module_v2() wi
332e0 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73  th a NULL.** des
332f0 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  tructor..*/.int 
33300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
33310 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
33320 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
33330 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
33340 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
33350 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
33360 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
33370 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
33380 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
33390 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
333a0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
333b0 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
333c0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
333d0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
333e0 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20  entData         
333f0 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
33400 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
33410 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  nect */.);.int s
33420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
33430 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  dule_v2(.  sqlit
33440 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
33450 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
33460 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
33470 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
33480 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
33490 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
334a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
334b0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
334c0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
334d0 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
334e0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
334f0 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
33500 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20  lientData,      
33510 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
33520 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
33530 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64  onnect */.  void
33540 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
33550 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65  *)     /* Module
33560 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
33570 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  tion */.);../*.*
33580 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
33590 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e  ual Table Instan
335a0 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ce Object.** KEY
335b0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
335c0 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  tab.**.** Every 
335d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
335e0 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
335f0 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
33600 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73  class.** of this
33610 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72   object to descr
33620 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72  ibe a particular
33630 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20   instance.** of 
33640 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
33650 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c  le].  Each subcl
33660 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
33670 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
33680 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
33690 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
336a0 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54  ementation..** T
336b0 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  he purpose of th
336c0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
336d0 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
336e0 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
336f0 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20  re.** common to 
33700 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
33710 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
33720 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65  * ^Virtual table
33730 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
33740 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
33750 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
33760 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
33770 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
33780 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
33790 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
337a0 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
337b0 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
337c0 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
337d0 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
337e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
337f0 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
33800 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
33810 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
33820 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68  rMsg.  ^After th
33830 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
33840 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
33850 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
33860 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
33870 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
33880 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
33890 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
338a0 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
338b0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
338c0 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
338d0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
338e0 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
338f0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
33900 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
33910 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
33920 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
33930 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
33940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33950 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
33960 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
33970 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
33980 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
33990 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
339a0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
339b0 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
339c0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
339d0 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
339e0 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
339f0 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
33a00 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
33a10 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
33a20 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
33a30 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
33a40 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
33a50 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  or {virtual tabl
33a60 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20  e cursor}.**.** 
33a70 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
33a80 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
33a90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
33aa0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
33ab0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
33ac0 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
33ad0 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
33ae0 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
33af0 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  e.** [virtual ta
33b00 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65  ble] and are use
33b10 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72  d.** to loop thr
33b20 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c  ough the virtual
33b30 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73   table.  Cursors
33b40 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
33b50 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
33b60 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20  e3_module.xOpen 
33b70 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  | xOpen] method 
33b80 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  of the module an
33b90 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a  d are destroyed.
33ba0 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ** by the [sqlit
33bb0 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65  e3_module.xClose
33bc0 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f   | xClose] metho
33bd0 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  d.  Cursors are 
33be0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  used.** by the [
33bf0 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74  xFilter], [xNext
33c00 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c  ], [xEof], [xCol
33c10 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69  umn], and [xRowi
33c20 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  d] methods.** of
33c30 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
33c40 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
33c50 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
33c60 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
33c70 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
33c80 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
33c90 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
33ca0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
33cb0 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
33cc0 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
33cd0 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
33ce0 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
33cf0 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
33d00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
33d10 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
33d20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
33d30 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
33d40 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
33d50 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
33d60 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
33d70 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
33d80 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
33d90 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
33da0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
33db0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
33dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
33dd0 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d  eclare The Schem
33de0 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54  a Of A Virtual T
33df0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  able.**.** ^The 
33e00 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
33e10 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
33e20 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61   of a.** [virtua
33e30 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
33e40 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66  call this interf
33e50 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  ace.** to declar
33e60 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
33e70 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
33e80 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
33e90 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
33ea0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
33eb0 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
33ec0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
33ed0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
33ee0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
33ef0 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *zSQL);../*.** C
33f00 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
33f10 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
33f20 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
33f30 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c  .**.** ^(Virtual
33f40 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
33f50 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
33f60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
33f70 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
33f80 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64  using the [xFind
33f90 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64  Function] method
33fa0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
33fb0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
33fc0 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20   .** But global 
33fd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
33fe0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
33ff0 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
34000 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
34010 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ded.)^.**.** ^(T
34020 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
34030 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
34040 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
34050 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
34060 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
34070 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
34080 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
34090 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
340a0 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
340b0 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
340c0 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
340d0 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
340e0 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d  .)^  ^The implem
340f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
34100 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
34110 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e  always causes an
34120 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65   exception to be
34130 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20   thrown.  So.** 
34140 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
34150 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72   is not good for
34160 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73   anything by its
34170 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a  elf.  Its only.*
34180 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20  * purpose is to 
34190 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72  be a placeholder
341a0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
341b0 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
341c0 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61  .** by a [virtua
341d0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74  l table]..*/.int
341e0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
341f0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
34200 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
34210 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
34220 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
34230 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
34240 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
34250 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
34260 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
34270 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
34280 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
34290 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
342a0 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
342b0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
342c0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
342d0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
342e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
342f0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
34300 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
34310 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
34320 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
34330 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
34340 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
34350 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
34360 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
34370 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
34380 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
34390 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
343a0 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
343b0 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
343c0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
343d0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
343e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
343f0 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
34400 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  BLOB.** KEYWORDS
34410 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
34420 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
34430 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
34440 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
34450 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
34460 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
34470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
34480 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
34490 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
344a0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
344b0 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20  .** ^Objects of 
344c0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
344d0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
344e0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
344f0 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
34500 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
34510 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54  _close()]..** ^T
34520 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
34530 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
34540 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
34550 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
34560 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
34570 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
34580 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
34590 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
345a0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
345b0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
345c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
345d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
345e0 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
345f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
34600 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
34610 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
34620 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
34630 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
34640 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
34650 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
34660 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
34670 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
34680 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
34690 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
346a0 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
346b0 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
346c0 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
346d0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
346e0 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
346f0 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
34700 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
34710 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
34720 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
34730 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
34740 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
34750 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
34760 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  e>)^.**.** ^If t
34770 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
34780 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
34790 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
347a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
347b0 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
347c0 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20  cess. ^If it is 
347d0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
347e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
347f0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74  d access..** ^It
34800 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
34810 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
34820 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
34830 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72  f an index or pr
34840 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f  imary .** key fo
34850 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b  r writing. ^If [
34860 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
34870 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61  traints] are ena
34880 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20  bled, it is .** 
34890 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
348a0 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
348b0 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
348c0 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20  [child key] for 
348d0 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  writing..**.** ^
348e0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
348f0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
34900 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
34910 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
34920 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
34930 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
34940 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
34950 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
34960 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65 72  ** appears after
34970 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
34980 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
34990 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75  e is connected u
349a0 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a  sing [ATTACH]..*
349b0 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20  * ^For the main 
349c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
349d0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
349e0 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e   is "main"..** ^
349f0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
34a00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
34a10 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
34a20 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
34a30 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
34a40 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
34a50 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64  e new [BLOB hand
34a60 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  le] is written.*
34a70 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74  * to *ppBlob. Ot
34a80 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
34a90 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
34aa0 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20  ned and *ppBlob 
34ab0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20  is set.** to be 
34ac0 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29  a null pointer.)
34ad0 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  ^.** ^This funct
34ae0 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61  ion sets the [da
34af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34b00 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  n] error code an
34b10 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
34b20 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
34b30 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
34b40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
34b50 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74  msg()] and relat
34b60 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e  ed.** functions.
34b70 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
34b80 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65  *ppBlob variable
34b90 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69   is always initi
34ba0 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77  alized in a.** w
34bb0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  ay that makes it
34bc0 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20   safe to invoke 
34bd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34be0 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f  ose()] on *ppBlo
34bf0 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  b.** regardless 
34c00 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f  of the success o
34c10 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69  r failure of thi
34c20 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
34c30 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74 68   ^(If the row th
34c40 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65  at a BLOB handle
34c50 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f   points to is mo
34c60 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20  dified by an.** 
34c70 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54  [UPDATE], [DELET
34c80 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f  E], or by [ON CO
34c90 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66  NFLICT] side-eff
34ca0 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ects.** then the
34cb0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
34cc0 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72  marked as "expir
34cd0 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ed"..** This is 
34ce0 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75  true if any colu
34cf0 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73  mn of the row is
34d00 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61   changed, even a
34d10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72   column.** other
34d20 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68   than the one th
34d30 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
34d40 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e   open on.)^.** ^
34d50 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
34d60 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
34d70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
34d80 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
34d90 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
34da0 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
34db0 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
34dc0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
34dd0 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20  ]..** ^(Changes 
34de0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
34df0 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
34e00 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
34e10 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64  re not.** rolled
34e20 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70   back by the exp
34e30 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42  iration of the B
34e40 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67  LOB.  Such chang
34e50 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  es will eventual
34e60 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20  ly.** commit if 
34e70 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
34e80 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
34e90 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  pletion.)^.**.**
34ea0 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74   ^Use the [sqlit
34eb0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
34ec0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65   interface to de
34ed0 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
34ee0 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65   of.** the opene
34ef0 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69  d blob.  ^The si
34f00 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79  ze of a blob may
34f10 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20   not be changed 
34f20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  by this.** inter
34f30 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b  face.  Use the [
34f40 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d  UPDATE] SQL comm
34f50 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  and to change th
34f60 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62  e size of a.** b
34f70 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lob..**.** ^The 
34f80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
34f90 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73  roblob()] and [s
34fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
34fb0 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66  roblob()] interf
34fc0 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20  aces.** and the 
34fd0 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c  built-in [zerobl
34fe0 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ob] SQL function
34ff0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66   can be used, if
35000 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20   desired,.** to 
35010 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c  create an empty,
35020 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f   zero-filled blo
35030 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65  b in which to re
35040 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e  ad or write usin
35050 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  g.** this interf
35060 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  ace..**.** To av
35070 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c  oid a resource l
35080 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20  eak, every open 
35090 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68  [BLOB handle] sh
350a0 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a  ould eventually.
350b0 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ** be released b
350c0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
350d0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
350e0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
350f0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20  e3_blob_open(.  
35100 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
35110 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63  t char *zDb,.  c
35120 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
35130 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e,.  const char 
35140 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69  *zColumn,.  sqli
35150 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a  te3_int64 iRow,.
35160 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73    int flags,.  s
35170 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70  qlite3_blob **pp
35180 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Blob.);../*.** C
35190 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41  API3REF: Close A
351a0 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
351b0 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70  ** ^Closes an op
351c0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
351d0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67  ..**.** ^Closing
351e0 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61   a BLOB shall ca
351f0 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  use the current 
35200 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63  transaction to c
35210 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72  ommit.** if ther
35220 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42  e are no other B
35230 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67  LOBs, no pending
35240 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35250 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a  ents, and the.**
35260 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35270 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f  tion is in [auto
35280 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a  commit mode]..**
35290 20 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20   ^If any writes 
352a0 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
352b0 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
352c0 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
352d0 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
352e0 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
352f0 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
35300 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e  ..**.** ^(Closin
35310 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
35320 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
35330 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
35340 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
35350 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
35360 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
35370 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
35380 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
35390 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
353a0 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68  .  Any errors th
353b0 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a  at occur during.
353c0 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72  ** closing are r
353d0 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e  eported as a non
353e0 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c  -zero return val
353f0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ue.)^.**.** ^(Th
35400 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
35410 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79   unconditionally
35420 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20  .  Even if this 
35430 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a  routine returns.
35440 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  ** an error code
35450 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74  , the BLOB is st
35460 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a  ill closed.)^.**
35470 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
35480 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
35490 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73   null pointer (s
354a0 75 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20  uch as would be 
354b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61  returned.** by a
354c0 20 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20   failed call to 
354d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
354e0 65 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d  en()]) is a harm
354f0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
35500 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
35510 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
35520 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
35530 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
35540 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
35550 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52  en BLOB.**.** ^R
35560 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
35570 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
35580 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20  BLOB accessible 
35590 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63  via the .** succ
355a0 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20  essfully opened 
355b0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
355c0 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
355d0 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63  nt.  ^The.** inc
355e0 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f  remental blob I/
355f0 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f  O routines can o
35600 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72  nly read or over
35610 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67  writing existing
35620 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74  .** blob content
35630 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68  ; they cannot ch
35640 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
35650 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54   a blob..**.** T
35660 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
35670 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
35680 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
35690 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
356a0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
356b0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
356c0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
356d0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
356e0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
356f0 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
35700 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
35710 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
35720 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
35730 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
35740 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
35750 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
35760 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
35770 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a  le behavior..*/.
35780 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
35790 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
357a0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
357b0 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
357c0 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
357d0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
357e0 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
357f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
35800 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
35810 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
35820 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
35830 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
35840 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
35850 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
35860 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
35870 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
35880 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
35890 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
358a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66  )^.**.** ^If off
358b0 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
358c0 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
358d0 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
358e0 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
358f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
35900 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
35910 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e  data is read.  ^
35920 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20  If N or iOffset 
35930 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
35940 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52  zero, [SQLITE_ER
35950 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
35960 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
35970 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69  read..** ^The si
35980 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28  ze of the blob (
35990 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
359a0 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
359b0 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
359c0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
359d0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
359e0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
359f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
35a00 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20   ^An attempt to 
35a10 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70  read from an exp
35a20 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
35a30 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
35a40 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
35a50 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
35a60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
35a70 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c  cess, sqlite3_bl
35a80 6f 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e  ob_read() return
35a90 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  s SQLITE_OK..** 
35aa0 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65  Otherwise, an [e
35ab0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
35ac0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
35ad0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
35ae0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ed.)^.**.** This
35af0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
35b00 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
35b10 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
35b20 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
35b30 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
35b40 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
35b50 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35b60 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
35b70 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
35b80 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
35b90 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
35ba0 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
35bb0 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
35bc0 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
35bd0 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
35be0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
35bf0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
35c00 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
35c10 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
35c20 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
35c30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35c40 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74  _blob_read(sqlit
35c50 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20  e3_blob *, void 
35c60 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69  *Z, int N, int i
35c70 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
35c80 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20  CAPI3REF: Write 
35c90 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42  Data Into A BLOB
35ca0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a   Incrementally.*
35cb0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
35cc0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77  ion is used to w
35cd0 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61  rite data into a
35ce0 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
35cf0 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63  dle] from a.** c
35d00 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62  aller-supplied b
35d10 75 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20  uffer. ^N bytes 
35d20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
35d30 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66  ed from the buff
35d40 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  er Z.** into the
35d50 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72   open BLOB, star
35d60 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
35d70 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49  Offset..**.** ^I
35d80 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  f the [BLOB hand
35d90 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  le] passed as th
35da0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35db0 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
35dc0 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28  for.** writing (
35dd0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
35de0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
35df0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73  blob_open()] was
35e00 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20   zero),.** this 
35e10 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
35e20 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   [SQLITE_READONL
35e30 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  Y]..**.** ^This 
35e40 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c  function may onl
35e50 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e  y modify the con
35e60 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f  tents of the BLO
35e70 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  B; it is.** not 
35e80 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72  possible to incr
35e90 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ease the size of
35ea0 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68   a BLOB using th
35eb0 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f  is API..** ^If o
35ec0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
35ed0 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74   less than N byt
35ee0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
35ef0 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20  of the BLOB,.** 
35f00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
35f10 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
35f20 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65  o data is writte
35f30 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20  n.  ^If N is.** 
35f40 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
35f50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
35f60 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
35f70 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
35f80 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66  ..** The size of
35f90 20 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68   the BLOB (and h
35fa0 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
35fb0 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
35fc0 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
35fd0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
35fe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
35ff0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
36000 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  face..**.** ^An 
36010 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  attempt to write
36020 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b   to an expired [
36030 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
36040 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
36050 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
36060 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72  ITE_ABORT].  ^Wr
36070 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42  ites to the BLOB
36080 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a   that occurred.*
36090 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c  * before the [BL
360a0 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72  OB handle] expir
360b0 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65  ed are not rolle
360c0 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a  d back by the.**
360d0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
360e0 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67  he handle, thoug
360f0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73  h of course thos
36100 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a  e changes might.
36110 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65  ** have been ove
36120 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
36130 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65  statement that e
36140 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20  xpired the BLOB 
36150 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20  handle.** or by 
36160 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e  other independen
36170 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  t statements..**
36180 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
36190 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  , sqlite3_blob_w
361a0 72 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53  rite() returns S
361b0 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68  QLITE_OK..** Oth
361c0 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72  erwise, an  [err
361d0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
361e0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
361f0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
36200 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
36210 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
36220 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
36230 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
36240 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
36250 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
36260 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
36270 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
36280 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
36290 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
362a0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
362b0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
362c0 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
362d0 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
362e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
362f0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
36300 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
36310 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
36320 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
36330 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
36340 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a  _blob_read()]..*
36350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
36360 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33  ob_write(sqlite3
36370 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76  _blob *, const v
36380 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69  oid *z, int n, i
36390 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
363a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
363b0 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
363c0 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
363d0 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
363e0 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
363f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
36400 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
36410 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
36420 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
36430 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
36440 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
36450 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c  Most SQLite buil
36460 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a  ds come with a.*
36470 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74  * single default
36480 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70   VFS that is app
36490 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65  ropriate for the
364a0 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
364b0 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e  ** New VFSes can
364c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
364d0 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65  nd existing VFSe
364e0 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73  s can be unregis
364f0 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f  tered..** The fo
36500 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
36510 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e  es are provided.
36520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36530 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
36540 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
36560 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61  VFS given its na
36570 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72  me..** ^Names ar
36580 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65  e case sensitive
36590 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20  ..** ^Names are 
365a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
365b0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
365c0 2a 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  * ^If there is n
365d0 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20  o match, a NULL 
365e0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
365f0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73  ned..** ^If zVfs
36600 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
36610 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  n the default VF
36620 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  S is returned..*
36630 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20  *.** ^New VFSes 
36640 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77  are registered w
36650 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  ith sqlite3_vfs_
36660 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e  register()..** ^
36670 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63  Each new VFS bec
36680 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74  omes the default
36690 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65   VFS if the make
366a0 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74  Dflt flag is set
366b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56  ..** ^The same V
366c0 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  FS can be regist
366d0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
366e0 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75  mes without inju
366f0 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20  ry..** ^To make 
36700 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
36710 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
36720 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
36730 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
36740 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
36750 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
36760 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
36770 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
36780 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
36790 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
367a0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
367b0 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
367c0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
367d0 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
367e0 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
367f0 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
36800 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
36810 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
36820 20 5e 55 6e 72 65 67 69 73 74 65 72 20 61 20 56   ^Unregister a V
36830 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
36840 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
36850 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
36860 2a 2a 20 5e 28 49 66 20 74 68 65 20 64 65 66 61  ** ^(If the defa
36870 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67  ult VFS is unreg
36880 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72  istered, another
36890 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61   VFS is chosen a
368a0 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  s.** the default
368b0 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f  .  The choice fo
368c0 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73  r the new VFS is
368d0 20 61 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f   arbitrary.)^.*/
368e0 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71  .sqlite3_vfs *sq
368f0 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63  lite3_vfs_find(c
36900 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e  onst char *zVfsN
36910 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ame);.int sqlite
36920 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73  3_vfs_register(s
36930 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
36940 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20   makeDflt);.int 
36950 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
36960 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
36970 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  fs*);../*.** CAP
36980 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a  I3REF: Mutexes.*
36990 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
369a0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
369b0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
369c0 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
369d0 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74  zation. Though t
369e0 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
369f0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
36a00 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
36a10 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
36a20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
36a30 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
36a40 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
36a50 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
36a60 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
36a70 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
36a80 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
36a90 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
36aa0 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
36ab0 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
36ac0 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
36ad0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
36ae0 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
36af0 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
36b00 69 6d 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  ime.  ^(The foll
36b10 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65  owing.** impleme
36b20 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61  ntations are ava
36b30 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51  ilable in the SQ
36b40 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a  Lite core:.**.**
36b50 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20   <ul>.** <li>   
36b60 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
36b70 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
36b80 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a  E_MUTEX_PTHREAD.
36b90 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
36ba0 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c  _MUTEX_W32.** <l
36bb0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
36bc0 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29  X_NOOP.** </ul>)
36bd0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  ^.**.** ^The SQL
36be0 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69  ITE_MUTEX_NOOP i
36bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
36c00 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e   a set of routin
36c10 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  es.** that does 
36c20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20  no real locking 
36c30 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61  and is appropria
36c40 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a  te for use in.**
36c50 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64   a single-thread
36c60 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  ed application. 
36c70 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54   ^The SQLITE_MUT
36c80 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54  EX_OS2,.** SQLIT
36c90 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c  E_MUTEX_PTHREAD,
36ca0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
36cb0 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61  X_W32 implementa
36cc0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70  tions.** are app
36cd0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
36ce0 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20   on OS/2, Unix, 
36cf0 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a  and Windows..**.
36d00 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69  ** ^(If SQLite i
36d10 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
36d20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  the SQLITE_MUTEX
36d30 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65  _APPDEF preproce
36d40 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65  ssor.** macro de
36d50 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53  fined (with "-DS
36d60 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44  QLITE_MUTEX_APPD
36d70 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20  EF=1"), then no 
36d80 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
36d90 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75  ntation is inclu
36da0 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ded with the lib
36db0 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61  rary. In this ca
36dc0 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  se the.** applic
36dd0 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
36de0 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78  y a custom mutex
36df0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36e00 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
36e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
36e20 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65  X] option of the
36e30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
36e40 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  ) function.** be
36e50 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c  fore calling sql
36e60 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
36e70 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70  ) or any other p
36e80 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a  ublic sqlite3_.*
36e90 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
36ea0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
36eb0 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a  itialize().)^.**
36ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36ed0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72  _mutex_alloc() r
36ee0 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73  outine allocates
36ef0 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20   a new.** mutex 
36f00 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
36f10 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66  inter to it. ^If
36f20 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
36f30 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74  .** that means t
36f40 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c  hat a mutex coul
36f50 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74  d not be allocat
36f60 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  ed.  ^SQLite.** 
36f70 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20  will unwind its 
36f80 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e  stack and return
36f90 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68   an error.  ^(Th
36fa0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
36fb0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
36fc0 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66  lloc() is one of
36fd0 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
36fe0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20  onstants:.**.** 
36ff0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
37000 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
37010 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
37020 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
37030 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
37040 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
37050 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  TER.** <li>  SQL
37060 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37070 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  _MEM.** <li>  SQ
37080 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37090 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20  C_MEM2.** <li>  
370a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
370b0 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e  TIC_PRNG.** <li>
370c0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
370d0 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69  TATIC_LRU.** <li
370e0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
370f0 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c  STATIC_LRU2.** <
37100 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  /ul>)^.**.** ^Th
37110 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73  e first two cons
37120 74 61 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55  tants (SQLITE_MU
37130 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
37140 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
37150 49 56 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71  IVE).** cause sq
37160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37170 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
37180 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e   a new mutex.  ^
37190 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
371a0 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
371b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
371c0 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
371d0 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
371e0 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
371f0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
37200 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20  is used..** The 
37210 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
37220 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
37230 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73  ed to make a dis
37240 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
37250 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  een SQLITE_MUTEX
37260 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53  _RECURSIVE and S
37270 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
37280 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
37290 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51  ot want to.  ^SQ
372a0 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72  Lite will only r
372b0 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69  equest a recursi
372c0 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63  ve mutex in.** c
372d0 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65  ases where it re
372e0 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20  ally needs one. 
372f0 20 5e 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f   ^If a faster no
37300 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  n-recursive mute
37310 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
37320 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
37330 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61   on the host pla
37340 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78  tform, the mutex
37350 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69   subsystem.** mi
37360 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20  ght return such 
37370 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f  a mutex in respo
37380 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55  nse to SQLITE_MU
37390 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20  TEX_FAST..**.** 
373a0 5e 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77  ^The other allow
373b0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
373c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
373d0 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67  lloc() (anything
373e0 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53   other.** than S
373f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
37400 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
37410 58 5f 52 45 43 55 52 53 49 56 45 29 20 65 61 63  X_RECURSIVE) eac
37420 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f  h return.** a po
37430 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69  inter to a stati
37440 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75  c preexisting mu
37450 74 65 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69  tex.  ^Six stati
37460 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
37470 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
37480 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
37490 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
374a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
374b0 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
374c0 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
374d0 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
374e0 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
374f0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
37500 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
37510 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
37520 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
37530 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
37540 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
37550 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
37560 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
37570 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
37580 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
37590 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
375a0 5e 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e  ^Note that if on
375b0 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63  e of the dynamic
375c0 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72   mutex parameter
375d0 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  s (SQLITE_MUTEX_
375e0 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54  FAST.** or SQLIT
375f0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
37600 45 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20  E) is used then 
37610 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
37620 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  loc().** returns
37630 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74   a different mut
37640 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ex on every call
37650 2e 20 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20  .  ^But for the 
37660 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
37670 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
37680 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
37690 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
376a0 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
376b0 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
376c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
376d0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
376e0 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f  ) routine deallo
376f0 63 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73  cates a previous
37700 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ly.** allocated 
37710 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20  dynamic mutex.  
37720 5e 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66  ^SQLite is caref
37730 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ul to deallocate
37740 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69   every.** dynami
37750 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20  c mutex that it 
37760 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20  allocates.  The 
37770 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20  dynamic mutexes 
37780 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a  must not be in.*
37790 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20  * use when they 
377a0 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
377b0 20 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20    Attempting to 
377c0 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61  deallocate a sta
377d0 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73  tic.** mutex res
377e0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
377f0 64 20 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51  d behavior.  ^SQ
37800 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c  Lite never deall
37810 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74  ocates.** a stat
37820 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20  ic mutex..**.** 
37830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
37840 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
37850 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
37860 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
37870 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
37880 61 20 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e  a mutex.  ^If an
37890 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20  other thread is 
378a0 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74  already within t
378b0 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c  he mutex,.** sql
378c0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
378d0 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e  () will block an
378e0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
378f0 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72  try() will retur
37900 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  n.** SQLITE_BUSY
37910 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
37920 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65  mutex_try() inte
37930 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53  rface returns [S
37940 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f  QLITE_OK].** upo
37950 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74  n successful ent
37960 72 79 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63  ry.  ^(Mutexes c
37970 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
37980 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
37990 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e  URSIVE can be en
379a0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
379b0 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
379c0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73   thread..** In s
379d0 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
379e0 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
379f0 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
37a00 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
37a10 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
37a20 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
37a30 65 72 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20  er.)^  ^(If the 
37a40 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65  same thread trie
37a50 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f  s to enter any o
37a60 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
37a70 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20  mutex more than 
37a80 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69  once, the behavi
37a90 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
37aa0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
37ab0 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a  never exhibit.**
37ac0 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69   such behavior i
37ad0 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66  n its own use of
37ae0 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a   mutexes.)^.**.*
37af0 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73  * ^(Some systems
37b00 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57   (for example, W
37b10 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f  indows 95) do no
37b20 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70  t support the op
37b30 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  eration.** imple
37b40 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65  mented by sqlite
37b50 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20  3_mutex_try().  
37b60 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73  On those systems
37b70 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  , sqlite3_mutex_
37b80 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c  try().** will al
37b90 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49  ways return SQLI
37ba0 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51  TE_BUSY.  The SQ
37bb0 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65  Lite core only e
37bc0 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69  ver uses.** sqli
37bd0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
37be0 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69  as an optimizati
37bf0 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63  on so this is ac
37c00 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f  ceptable behavio
37c10 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
37c20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
37c30 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78  ave() routine ex
37c40 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74  its a mutex that
37c50 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
37c60 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
37c70 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20  e same thread.  
37c80 20 5e 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a   ^(The behavior.
37c90 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ** is undefined 
37ca0 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20  if the mutex is 
37cb0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  not currently en
37cc0 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  tered by the.** 
37cd0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f  calling thread o
37ce0 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  r is not current
37cf0 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53  ly allocated.  S
37d00 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
37d10 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e  ver do either.)^
37d20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
37d30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
37d40 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
37d50 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  , sqlite3_mutex_
37d60 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c  try(), or.** sql
37d70 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
37d80 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
37d90 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74  nter, then all t
37da0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hree routines.**
37db0 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70   behave as no-op
37dc0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
37dd0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  o: [sqlite3_mute
37de0 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73  x_held()] and [s
37df0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
37e00 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  held()]..*/.sqli
37e10 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74  te3_mutex *sqlit
37e20 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69  e3_mutex_alloc(i
37e30 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
37e40 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c  3_mutex_free(sql
37e50 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
37e60 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
37e70 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d  _enter(sqlite3_m
37e80 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
37e90 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71  te3_mutex_try(sq
37ea0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
37eb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
37ec0 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f  x_leave(sqlite3_
37ed0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
37ee0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
37ef0 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
37f00 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
37f10 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
37f20 72 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c  re defines the l
37f30 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65  ow-level routine
37f40 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c  s.** used to all
37f50 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75  ocate and use mu
37f60 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75  texes..**.** Usu
37f70 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c  ally, the defaul
37f80 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  t mutex implemen
37f90 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64  tations provided
37fa0 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a   by SQLite are.*
37fb0 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f  * sufficient, ho
37fc0 77 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68  wever the user h
37fd0 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66  as the option of
37fe0 20 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20   substituting a 
37ff0 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d  custom.** implem
38000 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65  entation for spe
38010 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d  cialized deploym
38020 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20  ents or systems 
38030 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65  for which SQLite
38040 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  .** does not pro
38050 76 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20  vide a suitable 
38060 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
38070 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68  In this case, th
38080 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65  e user.** create
38090 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20  s and populates 
380a0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
380b0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f  his structure to
380c0 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69   pass.** to sqli
380d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f  te3_config() alo
380e0 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ng with the [SQL
380f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
38100 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64  ] option..** Add
38110 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e  itionally, an in
38120 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
38130 74 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20  tructure can be 
38140 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75  used as an.** ou
38150 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68  tput variable wh
38160 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20  en querying the 
38170 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63  system for the c
38180 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20  urrent mutex.** 
38190 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
381a0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
381b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
381c0 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  X] option..**.**
381d0 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74   ^The xMutexInit
381e0 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
381f0 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
38200 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
38210 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
38220 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  m initialization
38230 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
38240 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e  initialize() fun
38250 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78  ction..** ^The x
38260 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e  MutexInit routin
38270 65 20 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51  e is calle by SQ
38280 4c 69 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63  Lite exactly onc
38290 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66  e for each.** ef
382a0 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
382b0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
382c0 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ize()]..**.** ^T
382d0 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74  he xMutexEnd met
382e0 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
382f0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
38300 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
38310 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68  art of system sh
38320 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71  utdown by the sq
38330 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
38340 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a   function. The.*
38350 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
38360 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
38370 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72  is expected to r
38380 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74  elease all outst
38390 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72  anding.** resour
383a0 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ces obtained by 
383b0 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64  the mutex method
383c0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
383d0 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20  , especially.** 
383e0 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62  those obtained b
383f0 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74  y the xMutexInit
38400 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 78   method.  ^The x
38410 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e  MutexEnd().** in
38420 74 65 72 66 61 63 65 20 69 73 20 69 6e 76 6f 6b  terface is invok
38430 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  ed exactly once 
38440 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  for each call to
38450 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
38460 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  wn()]..**.** ^(T
38470 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76  he remaining sev
38480 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  en methods defin
38490 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
384a0 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f  ture (xMutexAllo
384b0 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65  c,.** xMutexFree
384c0 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78  , xMutexEnter, x
384d0 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78  MutexTry, xMutex
384e0 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c  Leave, xMutexHel
384f0 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e  d and.** xMutexN
38500 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e  otheld) implemen
38510 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  t the following 
38520 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70  interfaces (resp
38530 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a  ectively):.**.**
38540 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
38550 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
38560 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  alloc()] </li>.*
38570 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
38580 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d  e3_mutex_free()]
38590 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
385a0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
385b0 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a  _enter()] </li>.
385c0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
385d0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d  te3_mutex_try()]
385e0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
385f0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
38600 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a  _leave()] </li>.
38610 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
38620 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
38630 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
38640 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
38650 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c  x_notheld()] </l
38660 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
38670 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  .** The only dif
38680 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20  ference is that 
38690 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74  the public sqlit
386a0 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73  e3_XXX functions
386b0 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61   enumerated.** a
386c0 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67  bove silently ig
386d0 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74  nore any invocat
386e0 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61  ions that pass a
386f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
38700 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61  stead.** of a va
38710 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65  lid mutex handle
38720 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  . The implementa
38730 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74  tions of the met
38740 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20  hods defined.** 
38750 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
38760 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72  e are not requir
38770 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69  ed to handle thi
38780 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75  s case, the resu
38790 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e  lts.** of passin
387a0 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
387b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61   instead of a va
387c0 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65  lid mutex handle
387d0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a   are undefined.*
387e0 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63  * (i.e. it is ac
387f0 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76  ceptable to prov
38800 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  ide an implement
38810 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61  ation that segfa
38820 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73  ults if.** it is
38830 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70   passed a NULL p
38840 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54  ointer)..**.** T
38850 68 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20  he xMutexInit() 
38860 6d 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74  method must be t
38870 68 72 65 61 64 73 61 66 65 2e 20 20 5e 49 74 20  hreadsafe.  ^It 
38880 6d 75 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73  must be harmless
38890 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d   to.** invoke xM
388a0 75 74 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70  utexInit() mutip
388b0 6c 65 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20  le times within 
388c0 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
388d0 20 61 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20   and without.** 
388e0 69 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c  intervening call
388f0 73 20 74 6f 20 78 4d 75 74 65 78 45 6e 64